* [PATCH 0/2] cmake doc: modernize and cross-platform-ize the docs
@ 2022-12-19 10:32 Ævar Arnfjörð Bjarmason
2022-12-19 10:32 ` [PATCH 1/2] cmake: use "-S" and "-B" to specify source and build directories Ævar Arnfjörð Bjarmason
` (2 more replies)
0 siblings, 3 replies; 5+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-12-19 10:32 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Johannes Schindelin, Phillip Wood, Victoria Dye,
Eric Sunshine, Ævar Arnfjörð Bjarmason
Change the cmake docs to use one-command build instructions using
options that "cmake" supports an ill our supported versions, and in
2/2 re-arrange the docs to make it clearer which part of the
instructions are platform-specific.
Like the just-submitted [1] this extracted from [2], and the range
diff below is to [2]. The only change since [2] is a trivial reflow
change in the commit message.
There were no outstanding issues or feedback with this part of [2], so
hopefully this can advance relatively quickly.
1. https://lore.kernel.org/git/patch-1.1-0fa41115261-20221219T102205Z-avarab@gmail.com/T/#u
2. https://lore.kernel.org/git/cover-v6-00.15-00000000000-20221206T001617Z-avarab@gmail.com/
Ævar Arnfjörð Bjarmason (2):
cmake: use "-S" and "-B" to specify source and build directories
cmake: update instructions for portable CMakeLists.txt
contrib/buildsystems/CMakeLists.txt | 70 ++++++++++++++++++++---------
1 file changed, 50 insertions(+), 20 deletions(-)
Range-diff:
1: fc190b379cd < -: ----------- cmake: don't invoke msgfmt with --statistics
2: 1a11aa233a3 ! 1: 2411acc9d4c cmake: use "-S" and "-B" to specify source and build directories
@@ Commit message
cmake: use "-S" and "-B" to specify source and build directories
Rather than the multi-line "mkdir/cd/cmake" recipe provide an
- equivalent one-liner using the "-S" and "-B" options, and then suggest building with "make -C <build-dir>".
+ equivalent one-liner using the "-S" and "-B" options, and then suggest
+ building with "make -C <build-dir>".
The rest of these instructions discuss e.g. running tests from our
top-level "t/" directory, so it's more helpful to avoid changing the
3: b9ddb5db1d3 = 2: d6058ed0f22 cmake: update instructions for portable CMakeLists.txt
4: 7b7850c00ee < -: ----------- cmake: don't copy chainlint.pl to build directory
5: 82ecb797915 < -: ----------- cmake: chmod +x the bin-wrappers/* & SCRIPT_{SH,PERL} & git-p4
6: 1f326944a07 < -: ----------- cmake & test-lib.sh: add a $GIT_SOURCE_DIR variable
7: 973c8038f54 < -: ----------- cmake: set "USE_LIBPCRE2" in "GIT-BUILD-OPTIONS" for test-lib.sh
8: b8448c7a8a6 < -: ----------- Makefile + test-lib.sh: don't prefer cmake-built to make-built git
9: 5135e40969e < -: ----------- test-lib.sh: support a "GIT_TEST_BUILD_DIR"
10: 65204463730 < -: ----------- cmake: optionally be able to run tests before "ctest"
11: e25992b16f1 < -: ----------- cmake: support GIT_TEST_OPTS, abstract away WIN32 defaults
12: 4905ce5321d < -: ----------- cmake: increase test timeout on Windows only
13: 6c6b530965d < -: ----------- cmake: only look for "sh" in "C:/Program Files" on Windows
14: 563f1b9b045 < -: ----------- cmake: copy over git-p4.py for t983[56] perforce test
15: 917a884eb65 < -: ----------- CI: add a "linux-cmake-test" to run cmake & ctest on linux
--
2.39.0.1071.g97ce8966538
^ permalink raw reply [flat|nested] 5+ messages in thread
* [PATCH 1/2] cmake: use "-S" and "-B" to specify source and build directories
2022-12-19 10:32 [PATCH 0/2] cmake doc: modernize and cross-platform-ize the docs Ævar Arnfjörð Bjarmason
@ 2022-12-19 10:32 ` Ævar Arnfjörð Bjarmason
2022-12-19 10:32 ` [PATCH 2/2] cmake: update instructions for portable CMakeLists.txt Ævar Arnfjörð Bjarmason
2022-12-19 14:55 ` [PATCH 0/2] cmake doc: modernize and cross-platform-ize the docs Phillip Wood
2 siblings, 0 replies; 5+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-12-19 10:32 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Johannes Schindelin, Phillip Wood, Victoria Dye,
Eric Sunshine, Ævar Arnfjörð Bjarmason
Rather than the multi-line "mkdir/cd/cmake" recipe provide an
equivalent one-liner using the "-S" and "-B" options, and then suggest
building with "make -C <build-dir>".
The rest of these instructions discuss e.g. running tests from our
top-level "t/" directory, so it's more helpful to avoid changing the
user's current directory.
The "-S" and "-B" options were added in cmake v3.13.0, which is older
than the version we have a hard dependency on[1].
As an aside, the "-p" flag to "mkdir" in the pre-image wasn't needed,
as "contrib/buildsystems" is tracked
1. 061c2240b1b (Introduce CMake support for configuring Git, 2020-06-12)
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
contrib/buildsystems/CMakeLists.txt | 8 +++-----
1 file changed, 3 insertions(+), 5 deletions(-)
diff --git a/contrib/buildsystems/CMakeLists.txt b/contrib/buildsystems/CMakeLists.txt
index 8f8b6f375f7..5b22a9b217f 100644
--- a/contrib/buildsystems/CMakeLists.txt
+++ b/contrib/buildsystems/CMakeLists.txt
@@ -16,9 +16,7 @@ though, therefore the `File>Open>Folder...` option is preferred.
Instructions to run CMake manually:
- mkdir -p contrib/buildsystems/out
- cd contrib/buildsystems/out
- cmake ../ -DCMAKE_BUILD_TYPE=Release
+ cmake -S contrib/buildsystems -B contrib/buildsystems/out -DCMAKE_BUILD_TYPE=Release
This will build the git binaries in contrib/buildsystems/out
directory (our top-level .gitignore file knows to ignore contents of
@@ -36,8 +34,8 @@ NOTE: -DCMAKE_BUILD_TYPE is optional. For multi-config generators like Visual St
this option is ignored
This process generates a Makefile(Linux/*BSD/MacOS) , Visual Studio solution(Windows) by default.
-Run `make` to build Git on Linux/*BSD/MacOS.
-Open git.sln on Windows and build Git.
+Run `make -C contrib/buildsystems/out` to build Git on Linux/*BSD/MacOS.
+Open contrib/buildsystems/git.sln on Windows and build Git.
NOTE: By default CMake uses Makefile as the build tool on Linux and Visual Studio in Windows,
to use another tool say `ninja` add this to the command line when configuring.
--
2.39.0.1071.g97ce8966538
^ permalink raw reply related [flat|nested] 5+ messages in thread
* [PATCH 2/2] cmake: update instructions for portable CMakeLists.txt
2022-12-19 10:32 [PATCH 0/2] cmake doc: modernize and cross-platform-ize the docs Ævar Arnfjörð Bjarmason
2022-12-19 10:32 ` [PATCH 1/2] cmake: use "-S" and "-B" to specify source and build directories Ævar Arnfjörð Bjarmason
@ 2022-12-19 10:32 ` Ævar Arnfjörð Bjarmason
2022-12-19 14:55 ` [PATCH 0/2] cmake doc: modernize and cross-platform-ize the docs Phillip Wood
2 siblings, 0 replies; 5+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-12-19 10:32 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Johannes Schindelin, Phillip Wood, Victoria Dye,
Eric Sunshine, Ævar Arnfjörð Bjarmason
The instructions for running CMake went back & forth between *nix,
Windows and Visual Studio instructions Let's create headings and split
the existing instructions up into those new sections.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
contrib/buildsystems/CMakeLists.txt | 68 +++++++++++++++++++++--------
1 file changed, 50 insertions(+), 18 deletions(-)
diff --git a/contrib/buildsystems/CMakeLists.txt b/contrib/buildsystems/CMakeLists.txt
index 5b22a9b217f..80290edd72a 100644
--- a/contrib/buildsystems/CMakeLists.txt
+++ b/contrib/buildsystems/CMakeLists.txt
@@ -4,7 +4,31 @@
#[[
-Instructions how to use this in Visual Studio:
+== Overview ==
+
+The top-level Makefile is Git's primary build environment, and a lot
+of things are missing (and probably always will be) from this CMake
+alternative.
+
+The primary use-case for maintaining this CMake build recipe is to
+have nicer IDE integration on Windows.
+
+== Creating a build recipe ==
+
+The "cmake" command creates a build file from this recipe:
+
+ cmake -S contrib/buildsystems -B contrib/buildsystems/out -DCMAKE_BUILD_TYPE=Release
+
+Running this will create files in the contrib/buildsystems/out
+directory (our top-level .gitignore file knows to ignore contents of
+this directory).
+
+See "cmake options" below for a discussion of
+"-DCMAKE_BUILD_TYPE=Release" and other options to "cmake".
+
+== Building with Visual Visual Studio ==
+
+To use this in Visual Studio:
Open the worktree as a folder. Visual Studio 2019 and later will detect
the CMake configuration automatically and set everything up for you,
@@ -14,13 +38,33 @@ Note: Visual Studio also has the option of opening `CMakeLists.txt`
directly; Using this option, Visual Studio will not find the source code,
though, therefore the `File>Open>Folder...` option is preferred.
-Instructions to run CMake manually:
+By default CMake will install vcpkg locally to your source tree on configuration,
+to avoid this, add `-DNO_VCPKG=TRUE` to the command line when configuring.
- cmake -S contrib/buildsystems -B contrib/buildsystems/out -DCMAKE_BUILD_TYPE=Release
+== Building on Windows without Visual Studio ==
-This will build the git binaries in contrib/buildsystems/out
-directory (our top-level .gitignore file knows to ignore contents of
-this directory).
+Open contrib/buildsystems/git.sln and build Git. Or use the "msbuild"
+command-line tool (see our own ".github/workflows/main.yml" for a real
+example):
+
+ msbuild git.sln
+
+== Building on *nix ==
+
+On all other platforms running "cmake" will generate a Makefile; to
+build with it run:
+
+ make -C contrib/buildsystems/out
+
+It's also possible to use other generators, e.g. Ninja has arguably
+slightly better output. Add "-G Ninja" to the cmake command above,
+then:
+
+ ninja -C contrib/buildsystems/out
+
+== cmake options ==
+
+=== -DCMAKE_BUILD_TYPE=<type> ===
Possible build configurations(-DCMAKE_BUILD_TYPE) with corresponding
compiler flags
@@ -32,18 +76,6 @@ empty(default) :
NOTE: -DCMAKE_BUILD_TYPE is optional. For multi-config generators like Visual Studio
this option is ignored
-
-This process generates a Makefile(Linux/*BSD/MacOS) , Visual Studio solution(Windows) by default.
-Run `make -C contrib/buildsystems/out` to build Git on Linux/*BSD/MacOS.
-Open contrib/buildsystems/git.sln on Windows and build Git.
-
-NOTE: By default CMake uses Makefile as the build tool on Linux and Visual Studio in Windows,
-to use another tool say `ninja` add this to the command line when configuring.
-`-G Ninja`
-
-NOTE: By default CMake will install vcpkg locally to your source tree on configuration,
-to avoid this, add `-DNO_VCPKG=TRUE` to the command line when configuring.
-
]]
cmake_minimum_required(VERSION 3.14)
--
2.39.0.1071.g97ce8966538
^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH 0/2] cmake doc: modernize and cross-platform-ize the docs
2022-12-19 10:32 [PATCH 0/2] cmake doc: modernize and cross-platform-ize the docs Ævar Arnfjörð Bjarmason
2022-12-19 10:32 ` [PATCH 1/2] cmake: use "-S" and "-B" to specify source and build directories Ævar Arnfjörð Bjarmason
2022-12-19 10:32 ` [PATCH 2/2] cmake: update instructions for portable CMakeLists.txt Ævar Arnfjörð Bjarmason
@ 2022-12-19 14:55 ` Phillip Wood
2022-12-19 15:06 ` Ævar Arnfjörð Bjarmason
2 siblings, 1 reply; 5+ messages in thread
From: Phillip Wood @ 2022-12-19 14:55 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason, git
Cc: Junio C Hamano, Johannes Schindelin, Phillip Wood, Victoria Dye,
Eric Sunshine
Hi Ævar
On 19/12/2022 10:32, Ævar Arnfjörð Bjarmason wrote:
> Change the cmake docs to use one-command build instructions using
> options that "cmake" supports an ill our supported versions, and in
> 2/2 re-arrange the docs to make it clearer which part of the
> instructions are platform-specific.
>
> Like the just-submitted [1] this extracted from [2], and the range
> diff below is to [2]. The only change since [2] is a trivial reflow
> change in the commit message.
>
> There were no outstanding issues or feedback with this part of [2], so
> hopefully this can advance relatively quickly.
I'm afraid my inclination would be to let the people who actually use
CMake make any changes to the CMake documentation as I think they are
best placed to know what information is most important.
Best Wishes
Phillip
> 1. https://lore.kernel.org/git/patch-1.1-0fa41115261-20221219T102205Z-avarab@gmail.com/T/#u
> 2. https://lore.kernel.org/git/cover-v6-00.15-00000000000-20221206T001617Z-avarab@gmail.com/
>
> Ævar Arnfjörð Bjarmason (2):
> cmake: use "-S" and "-B" to specify source and build directories
> cmake: update instructions for portable CMakeLists.txt
>
> contrib/buildsystems/CMakeLists.txt | 70 ++++++++++++++++++++---------
> 1 file changed, 50 insertions(+), 20 deletions(-)
>
> Range-diff:
> 1: fc190b379cd < -: ----------- cmake: don't invoke msgfmt with --statistics
> 2: 1a11aa233a3 ! 1: 2411acc9d4c cmake: use "-S" and "-B" to specify source and build directories
> @@ Commit message
> cmake: use "-S" and "-B" to specify source and build directories
>
> Rather than the multi-line "mkdir/cd/cmake" recipe provide an
> - equivalent one-liner using the "-S" and "-B" options, and then suggest building with "make -C <build-dir>".
> + equivalent one-liner using the "-S" and "-B" options, and then suggest
> + building with "make -C <build-dir>".
>
> The rest of these instructions discuss e.g. running tests from our
> top-level "t/" directory, so it's more helpful to avoid changing the
> 3: b9ddb5db1d3 = 2: d6058ed0f22 cmake: update instructions for portable CMakeLists.txt
> 4: 7b7850c00ee < -: ----------- cmake: don't copy chainlint.pl to build directory
> 5: 82ecb797915 < -: ----------- cmake: chmod +x the bin-wrappers/* & SCRIPT_{SH,PERL} & git-p4
> 6: 1f326944a07 < -: ----------- cmake & test-lib.sh: add a $GIT_SOURCE_DIR variable
> 7: 973c8038f54 < -: ----------- cmake: set "USE_LIBPCRE2" in "GIT-BUILD-OPTIONS" for test-lib.sh
> 8: b8448c7a8a6 < -: ----------- Makefile + test-lib.sh: don't prefer cmake-built to make-built git
> 9: 5135e40969e < -: ----------- test-lib.sh: support a "GIT_TEST_BUILD_DIR"
> 10: 65204463730 < -: ----------- cmake: optionally be able to run tests before "ctest"
> 11: e25992b16f1 < -: ----------- cmake: support GIT_TEST_OPTS, abstract away WIN32 defaults
> 12: 4905ce5321d < -: ----------- cmake: increase test timeout on Windows only
> 13: 6c6b530965d < -: ----------- cmake: only look for "sh" in "C:/Program Files" on Windows
> 14: 563f1b9b045 < -: ----------- cmake: copy over git-p4.py for t983[56] perforce test
> 15: 917a884eb65 < -: ----------- CI: add a "linux-cmake-test" to run cmake & ctest on linux
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH 0/2] cmake doc: modernize and cross-platform-ize the docs
2022-12-19 14:55 ` [PATCH 0/2] cmake doc: modernize and cross-platform-ize the docs Phillip Wood
@ 2022-12-19 15:06 ` Ævar Arnfjörð Bjarmason
0 siblings, 0 replies; 5+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-12-19 15:06 UTC (permalink / raw)
To: phillip.wood
Cc: git, Junio C Hamano, Johannes Schindelin, Phillip Wood,
Victoria Dye, Eric Sunshine
On Mon, Dec 19 2022, Phillip Wood wrote:
> Hi Ævar
>
> On 19/12/2022 10:32, Ævar Arnfjörð Bjarmason wrote:
>> Change the cmake docs to use one-command build instructions using
>> options that "cmake" supports an ill our supported versions, and in
>> 2/2 re-arrange the docs to make it clearer which part of the
>> instructions are platform-specific.
>> Like the just-submitted [1] this extracted from [2], and the range
>> diff below is to [2]. The only change since [2] is a trivial reflow
>> change in the commit message.
>> There were no outstanding issues or feedback with this part of [2],
>> so
>> hopefully this can advance relatively quickly.
>
> I'm afraid my inclination would be to let the people who actually use
> CMake make any changes to the CMake documentation as I think they are
> best placed to know what information is most important.
I think that after kicking this "cmake" series back & forth for a while
I can be described as a person who "uses cmake", I also have cmake+ctest
as part of my local build & branch integration.
I'm not sure what else to do with this comment, if you think that
e.g. there might be some issue with the proposed changes here due to a
blindspot I have in not using it with MSVC can you comment on the
specific parts that you're concerned about?
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2022-12-19 15:10 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2022-12-19 10:32 [PATCH 0/2] cmake doc: modernize and cross-platform-ize the docs Ævar Arnfjörð Bjarmason
2022-12-19 10:32 ` [PATCH 1/2] cmake: use "-S" and "-B" to specify source and build directories Ævar Arnfjörð Bjarmason
2022-12-19 10:32 ` [PATCH 2/2] cmake: update instructions for portable CMakeLists.txt Ævar Arnfjörð Bjarmason
2022-12-19 14:55 ` [PATCH 0/2] cmake doc: modernize and cross-platform-ize the docs Phillip Wood
2022-12-19 15:06 ` Ævar Arnfjörð Bjarmason
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).