{"thread":{"id":"58977","subject":"[PATCH 0/2] cmake doc: modernize and cross-platform-ize the docs","startedAt":"2022-12-19T10:32:58Z","lastAt":"2022-12-19T15:10:45Z","messageCount":5,"participants":["Ævar Arnfjörð Bjarmason","Phillip Wood"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"469276","messageId":"cover-0.2-00000000000-20221219T102813Z-avarab@gmail.com","threadId":"58977","inReplyTo":null,"subject":"[PATCH 0/2] cmake doc: modernize and cross-platform-ize the docs","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-12-19T10:32:44Z","receivedAt":"2022-12-19T10:32:58Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Change the cmake docs to use one-command build instructions using\noptions that \"cmake\" supports an ill our supported versions, and in\n2/2 re-arrange the docs to make it clearer which part of the\ninstructions are platform-specific.\n\nLike the just-submitted [1] this extracted from [2], and the range\ndiff below is to [2]. The only change since [2] is a trivial reflow\nchange in the commit message.\n\nThere were no outstanding issues or feedback with this part of [2], so\nhopefully this can advance relatively quickly.\n\n1. https://lore.kernel.org/git/patch-1.1-0fa41115261-20221219T102205Z-avarab@gmail.com/T/#u\n2. https://lore.kernel.org/git/cover-v6-00.15-00000000000-20221206T001617Z-avarab@gmail.com/\n\nÆvar Arnfjörð Bjarmason (2):\n  cmake: use \"-S\" and \"-B\" to specify source and build directories\n  cmake: update instructions for portable CMakeLists.txt\n\n contrib/buildsystems/CMakeLists.txt | 70 ++++++++++++++++++++---------\n 1 file changed, 50 insertions(+), 20 deletions(-)\n\nRange-diff:\n 1:  fc190b379cd <  -:  ----------- cmake: don't invoke msgfmt with --statistics\n 2:  1a11aa233a3 !  1:  2411acc9d4c cmake: use \"-S\" and \"-B\" to specify source and build directories\n    @@ Commit message\n         cmake: use \"-S\" and \"-B\" to specify source and build directories\n     \n         Rather than the multi-line \"mkdir/cd/cmake\" recipe provide an\n    -    equivalent one-liner using the \"-S\" and \"-B\" options, and then suggest building with \"make -C <build-dir>\".\n    +    equivalent one-liner using the \"-S\" and \"-B\" options, and then suggest\n    +    building with \"make -C <build-dir>\".\n     \n         The rest of these instructions discuss e.g. running tests from our\n         top-level \"t/\" directory, so it's more helpful to avoid changing the\n 3:  b9ddb5db1d3 =  2:  d6058ed0f22 cmake: update instructions for portable CMakeLists.txt\n 4:  7b7850c00ee <  -:  ----------- cmake: don't copy chainlint.pl to build directory\n 5:  82ecb797915 <  -:  ----------- cmake: chmod +x the bin-wrappers/* & SCRIPT_{SH,PERL} & git-p4\n 6:  1f326944a07 <  -:  ----------- cmake & test-lib.sh: add a $GIT_SOURCE_DIR variable\n 7:  973c8038f54 <  -:  ----------- cmake: set \"USE_LIBPCRE2\" in \"GIT-BUILD-OPTIONS\" for test-lib.sh\n 8:  b8448c7a8a6 <  -:  ----------- Makefile + test-lib.sh: don't prefer cmake-built to make-built git\n 9:  5135e40969e <  -:  ----------- test-lib.sh: support a \"GIT_TEST_BUILD_DIR\"\n10:  65204463730 <  -:  ----------- cmake: optionally be able to run tests before \"ctest\"\n11:  e25992b16f1 <  -:  ----------- cmake: support GIT_TEST_OPTS, abstract away WIN32 defaults\n12:  4905ce5321d <  -:  ----------- cmake: increase test timeout on Windows only\n13:  6c6b530965d <  -:  ----------- cmake: only look for \"sh\" in \"C:/Program Files\" on Windows\n14:  563f1b9b045 <  -:  ----------- cmake: copy over git-p4.py for t983[56] perforce test\n15:  917a884eb65 <  -:  ----------- CI: add a \"linux-cmake-test\" to run cmake & ctest on linux\n-- \n2.39.0.1071.g97ce8966538\n\n"},{"id":"469277","messageId":"patch-1.2-2411acc9d4c-20221219T102813Z-avarab@gmail.com","threadId":"58977","inReplyTo":"cover-0.2-00000000000-20221219T102813Z-avarab@gmail.com","subject":"[PATCH 1/2] cmake: use \"-S\" and \"-B\" to specify source and build directories","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-12-19T10:32:45Z","receivedAt":"2022-12-19T10:33:01Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Rather than the multi-line \"mkdir/cd/cmake\" recipe provide an\nequivalent one-liner using the \"-S\" and \"-B\" options, and then suggest\nbuilding with \"make -C <build-dir>\".\n\nThe rest of these instructions discuss e.g. running tests from our\ntop-level \"t/\" directory, so it's more helpful to avoid changing the\nuser's current directory.\n\nThe \"-S\" and \"-B\" options were added in cmake v3.13.0, which is older\nthan the version we have a hard dependency on[1].\n\nAs an aside, the \"-p\" flag to \"mkdir\" in the pre-image wasn't needed,\nas \"contrib/buildsystems\" is tracked\n\n1. 061c2240b1b (Introduce CMake support for configuring Git, 2020-06-12)\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n contrib/buildsystems/CMakeLists.txt | 8 +++-----\n 1 file changed, 3 insertions(+), 5 deletions(-)\n\ndiff --git a/contrib/buildsystems/CMakeLists.txt b/contrib/buildsystems/CMakeLists.txt\nindex 8f8b6f375f7..5b22a9b217f 100644\n--- a/contrib/buildsystems/CMakeLists.txt\n+++ b/contrib/buildsystems/CMakeLists.txt\n@@ -16,9 +16,7 @@ though, therefore the `File>Open>Folder...` option is preferred.\n \n Instructions to run CMake manually:\n \n-    mkdir -p contrib/buildsystems/out\n-    cd contrib/buildsystems/out\n-    cmake ../ -DCMAKE_BUILD_TYPE=Release\n+    cmake -S contrib/buildsystems -B contrib/buildsystems/out -DCMAKE_BUILD_TYPE=Release\n \n This will build the git binaries in contrib/buildsystems/out\n directory (our top-level .gitignore file knows to ignore contents of\n@@ -36,8 +34,8 @@ NOTE: -DCMAKE_BUILD_TYPE is optional. For multi-config generators like Visual St\n this option is ignored\n \n This process generates a Makefile(Linux/*BSD/MacOS) , Visual Studio solution(Windows) by default.\n-Run `make` to build Git on Linux/*BSD/MacOS.\n-Open git.sln on Windows and build Git.\n+Run `make -C contrib/buildsystems/out` to build Git on Linux/*BSD/MacOS.\n+Open contrib/buildsystems/git.sln on Windows and build Git.\n \n NOTE: By default CMake uses Makefile as the build tool on Linux and Visual Studio in Windows,\n to use another tool say `ninja` add this to the command line when configuring.\n-- \n2.39.0.1071.g97ce8966538\n\n"},{"id":"469278","messageId":"patch-2.2-d6058ed0f22-20221219T102813Z-avarab@gmail.com","threadId":"58977","inReplyTo":"cover-0.2-00000000000-20221219T102813Z-avarab@gmail.com","subject":"[PATCH 2/2] cmake: update instructions for portable CMakeLists.txt","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-12-19T10:32:46Z","receivedAt":"2022-12-19T10:33:04Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"The instructions for running CMake went back & forth between *nix,\nWindows and Visual Studio instructions Let's create headings and split\nthe existing instructions up into those new sections.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n contrib/buildsystems/CMakeLists.txt | 68 +++++++++++++++++++++--------\n 1 file changed, 50 insertions(+), 18 deletions(-)\n\ndiff --git a/contrib/buildsystems/CMakeLists.txt b/contrib/buildsystems/CMakeLists.txt\nindex 5b22a9b217f..80290edd72a 100644\n--- a/contrib/buildsystems/CMakeLists.txt\n+++ b/contrib/buildsystems/CMakeLists.txt\n@@ -4,7 +4,31 @@\n \n #[[\n \n-Instructions how to use this in Visual Studio:\n+== Overview ==\n+\n+The top-level Makefile is Git's primary build environment, and a lot\n+of things are missing (and probably always will be) from this CMake\n+alternative.\n+\n+The primary use-case for maintaining this CMake build recipe is to\n+have nicer IDE integration on Windows.\n+\n+== Creating a build recipe ==\n+\n+The \"cmake\" command creates a build file from this recipe:\n+\n+    cmake -S contrib/buildsystems -B contrib/buildsystems/out -DCMAKE_BUILD_TYPE=Release\n+\n+Running this will create files in the contrib/buildsystems/out\n+directory (our top-level .gitignore file knows to ignore contents of\n+this directory).\n+\n+See \"cmake options\" below for a discussion of\n+\"-DCMAKE_BUILD_TYPE=Release\" and other options to \"cmake\".\n+\n+== Building with Visual Visual Studio ==\n+\n+To use this in Visual Studio:\n \n Open the worktree as a folder. Visual Studio 2019 and later will detect\n the CMake configuration automatically and set everything up for you,\n@@ -14,13 +38,33 @@ Note: Visual Studio also has the option of opening `CMakeLists.txt`\n directly; Using this option, Visual Studio will not find the source code,\n though, therefore the `File>Open>Folder...` option is preferred.\n \n-Instructions to run CMake manually:\n+By default CMake will install vcpkg locally to your source tree on configuration,\n+to avoid this, add `-DNO_VCPKG=TRUE` to the command line when configuring.\n \n-    cmake -S contrib/buildsystems -B contrib/buildsystems/out -DCMAKE_BUILD_TYPE=Release\n+== Building on Windows without Visual Studio ==\n \n-This will build the git binaries in contrib/buildsystems/out\n-directory (our top-level .gitignore file knows to ignore contents of\n-this directory).\n+Open contrib/buildsystems/git.sln and build Git. Or use the \"msbuild\"\n+command-line tool (see our own \".github/workflows/main.yml\" for a real\n+example):\n+\n+\tmsbuild git.sln\n+\n+== Building on *nix ==\n+\n+On all other platforms running \"cmake\" will generate a Makefile; to\n+build with it run:\n+\n+\tmake -C contrib/buildsystems/out\n+\n+It's also possible to use other generators, e.g. Ninja has arguably\n+slightly better output. Add \"-G Ninja\" to the cmake command above,\n+then:\n+\n+\tninja -C contrib/buildsystems/out\n+\n+== cmake options ==\n+\n+=== -DCMAKE_BUILD_TYPE=<type> ===\n \n Possible build configurations(-DCMAKE_BUILD_TYPE) with corresponding\n compiler flags\n@@ -32,18 +76,6 @@ empty(default) :\n \n NOTE: -DCMAKE_BUILD_TYPE is optional. For multi-config generators like Visual Studio\n this option is ignored\n-\n-This process generates a Makefile(Linux/*BSD/MacOS) , Visual Studio solution(Windows) by default.\n-Run `make -C contrib/buildsystems/out` to build Git on Linux/*BSD/MacOS.\n-Open contrib/buildsystems/git.sln on Windows and build Git.\n-\n-NOTE: By default CMake uses Makefile as the build tool on Linux and Visual Studio in Windows,\n-to use another tool say `ninja` add this to the command line when configuring.\n-`-G Ninja`\n-\n-NOTE: By default CMake will install vcpkg locally to your source tree on configuration,\n-to avoid this, add `-DNO_VCPKG=TRUE` to the command line when configuring.\n-\n ]]\n cmake_minimum_required(VERSION 3.14)\n \n-- \n2.39.0.1071.g97ce8966538\n\n"},{"id":"469291","messageId":"f67e0281-8a14-669d-0d1c-ed0b1351a64a@dunelm.org.uk","threadId":"58977","inReplyTo":"cover-0.2-00000000000-20221219T102813Z-avarab@gmail.com","subject":"Re: [PATCH 0/2] cmake doc: modernize and cross-platform-ize the docs","fromName":"Phillip Wood","fromEmail":"phillip.wood123@gmail.com","sentAt":"2022-12-19T14:55:34Z","receivedAt":"2022-12-19T14:59:02Z","isPatch":true,"sender":{"key":"phillip.wood@dunelm.org.uk","avatar":null},"body":"Hi Ævar\n\nOn 19/12/2022 10:32, Ævar Arnfjörð Bjarmason wrote:\n> Change the cmake docs to use one-command build instructions using\n> options that \"cmake\" supports an ill our supported versions, and in\n> 2/2 re-arrange the docs to make it clearer which part of the\n> instructions are platform-specific.\n> \n> Like the just-submitted [1] this extracted from [2], and the range\n> diff below is to [2]. The only change since [2] is a trivial reflow\n> change in the commit message.\n> \n> There were no outstanding issues or feedback with this part of [2], so\n> hopefully this can advance relatively quickly.\n\nI'm afraid my inclination would be to let the people who actually use \nCMake make any changes to the CMake documentation as I think they are \nbest placed to know what information is most important.\n\nBest Wishes\n\nPhillip\n\n> 1. https://lore.kernel.org/git/patch-1.1-0fa41115261-20221219T102205Z-avarab@gmail.com/T/#u\n> 2. https://lore.kernel.org/git/cover-v6-00.15-00000000000-20221206T001617Z-avarab@gmail.com/\n> \n> Ævar Arnfjörð Bjarmason (2):\n>    cmake: use \"-S\" and \"-B\" to specify source and build directories\n>    cmake: update instructions for portable CMakeLists.txt\n> \n>   contrib/buildsystems/CMakeLists.txt | 70 ++++++++++++++++++++---------\n>   1 file changed, 50 insertions(+), 20 deletions(-)\n> \n> Range-diff:\n>   1:  fc190b379cd <  -:  ----------- cmake: don't invoke msgfmt with --statistics\n>   2:  1a11aa233a3 !  1:  2411acc9d4c cmake: use \"-S\" and \"-B\" to specify source and build directories\n>      @@ Commit message\n>           cmake: use \"-S\" and \"-B\" to specify source and build directories\n>       \n>           Rather than the multi-line \"mkdir/cd/cmake\" recipe provide an\n>      -    equivalent one-liner using the \"-S\" and \"-B\" options, and then suggest building with \"make -C <build-dir>\".\n>      +    equivalent one-liner using the \"-S\" and \"-B\" options, and then suggest\n>      +    building with \"make -C <build-dir>\".\n>       \n>           The rest of these instructions discuss e.g. running tests from our\n>           top-level \"t/\" directory, so it's more helpful to avoid changing the\n>   3:  b9ddb5db1d3 =  2:  d6058ed0f22 cmake: update instructions for portable CMakeLists.txt\n>   4:  7b7850c00ee <  -:  ----------- cmake: don't copy chainlint.pl to build directory\n>   5:  82ecb797915 <  -:  ----------- cmake: chmod +x the bin-wrappers/* & SCRIPT_{SH,PERL} & git-p4\n>   6:  1f326944a07 <  -:  ----------- cmake & test-lib.sh: add a $GIT_SOURCE_DIR variable\n>   7:  973c8038f54 <  -:  ----------- cmake: set \"USE_LIBPCRE2\" in \"GIT-BUILD-OPTIONS\" for test-lib.sh\n>   8:  b8448c7a8a6 <  -:  ----------- Makefile + test-lib.sh: don't prefer cmake-built to make-built git\n>   9:  5135e40969e <  -:  ----------- test-lib.sh: support a \"GIT_TEST_BUILD_DIR\"\n> 10:  65204463730 <  -:  ----------- cmake: optionally be able to run tests before \"ctest\"\n> 11:  e25992b16f1 <  -:  ----------- cmake: support GIT_TEST_OPTS, abstract away WIN32 defaults\n> 12:  4905ce5321d <  -:  ----------- cmake: increase test timeout on Windows only\n> 13:  6c6b530965d <  -:  ----------- cmake: only look for \"sh\" in \"C:/Program Files\" on Windows\n> 14:  563f1b9b045 <  -:  ----------- cmake: copy over git-p4.py for t983[56] perforce test\n> 15:  917a884eb65 <  -:  ----------- CI: add a \"linux-cmake-test\" to run cmake & ctest on linux\n"},{"id":"469294","messageId":"221219.86h6xrzaxd.gmgdl@evledraar.gmail.com","threadId":"58977","inReplyTo":"f67e0281-8a14-669d-0d1c-ed0b1351a64a@dunelm.org.uk","subject":"Re: [PATCH 0/2] cmake doc: modernize and cross-platform-ize the docs","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-12-19T15:06:13Z","receivedAt":"2022-12-19T15:10:45Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Mon, Dec 19 2022, Phillip Wood wrote:\n\n> Hi Ævar\n>\n> On 19/12/2022 10:32, Ævar Arnfjörð Bjarmason wrote:\n>> Change the cmake docs to use one-command build instructions using\n>> options that \"cmake\" supports an ill our supported versions, and in\n>> 2/2 re-arrange the docs to make it clearer which part of the\n>> instructions are platform-specific.\n>> Like the just-submitted [1] this extracted from [2], and the range\n>> diff below is to [2]. The only change since [2] is a trivial reflow\n>> change in the commit message.\n>> There were no outstanding issues or feedback with this part of [2],\n>> so\n>> hopefully this can advance relatively quickly.\n>\n> I'm afraid my inclination would be to let the people who actually use\n> CMake make any changes to the CMake documentation as I think they are \n> best placed to know what information is most important.\n\nI think that after kicking this \"cmake\" series back & forth for a while\nI can be described as a person who \"uses cmake\", I also have cmake+ctest\nas part of my local build & branch integration.\n\nI'm not sure what else to do with this comment, if you think that\ne.g. there might be some issue with the proposed changes here due to a\nblindspot I have in not using it with MSVC can you comment on the\nspecific parts that you're concerned about?\n"}]}