CMake usage updates to INSTALL-CMAKE.md by phetdam · Pull Request #16329 · curl/curl

phetdam · 2025-02-14T07:57:34Z

This PR updates the CMake build/install docs in docs/INSTALL-CMAKE.md, in particular focusing on the use of libcurl from CMake using find_package as well as the newly added features/protocols support via using COMPONENTS or OPTIONAL_COMPONENTS with find_package. See #15854 for initial discussion and the corresponding PR #15858 that was merged.

Some additional best-practices notes are added, for example:

Encouraging building out-of-source
Using --config with cmake --build for multi-config CMake generators, not CMAKE_BUILD_TYPE

We also add a CURL CMake-specific tip on using CMAKE_INSTALL_PREFIX during configure time to set the install prefix, not using --prefix when running cmake --install so curl-config output is consistent.

* Links to jump to relevant sections more quickly (build migration, CMake options) * Notes on best practices, e.g. build out-of-source, single vs. multi config * New section on usage from CMake, in particular features/protocols support * Update some of the build migration sections (multi-config notes)

phetdam · 2025-02-14T08:17:43Z

Spellcheck did not like FindCURL and NMake. Will add those to .github/scripts/spellcheck.words to appease it.

…ore list

bagder

Thanks! I have some ideas on how the language can be polished somewhat.

bagder · 2025-02-14T08:38:58Z


    $ cmake .

+Note, however, that it is recommended to build apart from the source tree, to


I think "apart" sounds a bit odd.

Suggested change

Note, however, that it is recommended to build apart from the source tree, to

It is recommended to build curl outside of the source tree, to

Yes, I agree. I think I chose this wording because earlier in the section, an out-of -source build is referred to as building "apart from the source tree", so I decided to keep this same language.

I definitely think your suggestion has better wording.

Actually, I will move this content upwards to the bullets where the in-source and separate build directory methods of running the CMake configure are being showcased. It's more natural to put this info there.

vszakats · 2025-02-14T18:08:17Z

+produced by the `curl-config` script is determined at CMake configure time. If
+you want to set a custom install prefix for CURL, use the
+[`CMAKE_INSTALL_PREFIX`](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html)
+when configuring the CMake build.


Unless curl behaves differently than most other projects out there, I'd rather omit general, non-curl specific, advice about CMAKE_INSTALL_PREFIX and --prefix, or at least make it less strong by dropping emphasis.

If curl needs special handling compared to other CMake builds, we should probably aim to fix the issue rather than document it.

We can drop the emphasis. However, the CMAKE_INSTALL_PREFIX and curl-config relationship is definitely specific to the curl project. I thought I made a note about this in #15854, but I clearly did not, and I only remembered this relationship while working on the documentation changes.

I'm not sure about other people, but when I do local build-from-source stuff on Windows I generally prefer to install into %HOME%/abc-major.minor.patch or something similar using --prefix during the cmake --install step. However, curl-config --prefix will instead report the value of CMAKE_INSTALL_PREFIX because it has already been configured as such. I suppose that supporting the use of --prefix will require an install(SCRIPT ...) rule to reconfigure curl-config on-the-fly with an updated install prefix as a pre-install action.

It looks fairly common that non-CMake files like *.pc and *-config are non-relocatable and need the prefix configured early. On a quick check, none of the curl dependencies do install(SCRIPT ..) and require this.

(On the flipside, LibreSSL breaks curl-for-win if using CMAKE_INSTALL_PREFIX because it embeds the custom local path (prefix) into the binary, which is undesired.)

I'm still not convinced this advice is necessary here.

I suppose that in the wild there may not be much support for --prefix (I think it was added in 3.15) because it is more of a recent option. Can't say how many others (besides me) like to use this, but I did some messing around to see if curl-config could be reconfigured before installation and that was already some work (and I haven't gotten it working). Since there's also the .pc file to worry about, supporting --prefix is probably not worth the effort; essentially both have to be reconfigured for each cmake --install invocation.

But if CMAKE_INSTALL_PREFIX is not going to work correctly we definitely should document that. Installing into a non-default root is pretty common, especially on Windows (to avoid Program Files, etc.) :(

CMAKE_INSTALL_PREFIX should be fine with curl and most other project too. LibreSSL is an outlier and not a concern regarding curl docs.

Since this recommendation is true for most projects, I still think this is something we can leave out from curl docs, though I don't feel strongly about it. If it helps using CMake with curl, we can have it here.

Yes, CMAKE_INSTALL_PREFIX works as expected with curl. But I think I will leave the cmake --install --prefix note in there since it is not 100% expected behavior. I'll also go and look over my changes in case of weird wording.

Co-authored-by: Daniel Stenberg <daniel@haxx.se>

…ral place

…mary

phetdam · 2025-02-17T06:07:12Z

Ooh, some CI test fails. The msys2 one just seems to be a GitHub Actions timeout (reached CI job runtime limit), but the other two have failing test cases (1196 failed for maketgz, 1631 + 1632 failed for FreeBSD).

I should keep the branch up to date anyways and it will be good to just re-run CI in case of flakiness.

…n section modified: .github/scripts/spellcheck.words Remove NMake (no longer using in a context that will be flagged) modified: docs/INSTALL-CMAKE.md Only one sentence for single vs. multi-config generator since we have link

vszakats · 2025-02-21T13:43:36Z

@phetdam Left a nit note about indentation. Apart from it, this LGTM.

edit: the timeouts (or hangs really) sometimes happen on the Windows runners. You may ignore them.

phetdam · 2025-02-23T03:36:40Z

@phetdam Left a nit note about indentation. Apart from it, this LGTM.

edit: the timeouts (or hangs really) sometimes happen on the Windows runners. You may ignore them.

Great! I'll fix the indentation and good to know that the CI failures aren't from some mysterious cause.

vszakats · 2025-02-24T23:19:33Z

@phetdam: Let me know when you're ready for merge.

phetdam · 2025-02-25T06:26:09Z

@phetdam: Let me know when you're ready for merge.

Just need to make a couple tweaks and I'll be good :)

phetdam · 2025-02-25T06:32:25Z

@vszakats Alright, I put a couple final tweaks and I think I'm now ready for merge.

vszakats · 2025-02-25T12:04:51Z

Thank you @phetdam, this is merged now!

This PR updates the CMake build/install docs in `docs/INSTALL-CMAKE.md`, in particular focusing on the use of libcurl from CMake using `find_package` as well as the newly added features/protocols support via using `COMPONENTS` or `OPTIONAL_COMPONENTS` with `find_package`. See curl#15854 for initial discussion and the corresponding PR curl#15858 that was merged. Some additional best-practices notes are added, for example: * Encouraging building out-of-source * Using `--config` with `cmake --build` for multi-config CMake generators, not `CMAKE_BUILD_TYPE` We also add a CURL CMake-specific tip on using `CMAKE_INSTALL_PREFIX` during configure time to set the install prefix, not using `--prefix` when running `cmake --install` so `curl-config` output is consistent. Closes curl#16329

phetdam added 4 commits February 14, 2025 02:28

INSTALL-CMAKE.md: update content in find_package section

2860ef9

Merge branch 'master' into features/update-INSTALL-CMAKE

a5b725d

INSTALL-CMAKE.md: add one-sentence preface

2e04cd4

github-actions bot added build cmake documentation labels Feb 14, 2025

INSTALL-CMAKE.md: attempt to appease badwords.pl

9fe1c54

spellcheck.words: add FindCURL and NMake (note capitalization) to ign…

3bc944c

…ore list

github-actions bot added the CI Continuous Integration label Feb 14, 2025

bagder reviewed Feb 14, 2025

View reviewed changes

vszakats reviewed Feb 14, 2025

View reviewed changes

Comment thread docs/INSTALL-CMAKE.md Outdated

vszakats reviewed Feb 14, 2025

View reviewed changes

Comment thread docs/INSTALL-CMAKE.md Outdated

vszakats reviewed Feb 14, 2025

View reviewed changes

phetdam and others added 9 commits February 15, 2025 21:44

INSTALL-CMAKE.md: fix target_link_libraries usage + typo

41a510a

INSTALL-CMAKE.md: fix summary line for IDE project migration section

5005f82

INSTALL-CMAKE.md: use --parallel over -j

cad9775

INSTALL-CMAKE.md: use angle brackets for VC + keep only link

752bc5a

apply verbatim suggestions from code review

5018772

Co-authored-by: Daniel Stenberg <daniel@haxx.se>

INSTALL-CMAKE.md: put note on separate build directory in a more natu…

52b45ac

…ral place

INSTALL-CMAKE.md: remove emphasis

202ff35

INSTALL-CMAKE.md: don't start off with "note"

d7fff08

INSTALL-CMAKE.md: change "noted previously" semantics into better sum…

c75b005

…mary

phetdam added 2 commits February 17, 2025 01:07

Merge branch 'master' into features/update-INSTALL-CMAKE

301d50d

vszakats reviewed Feb 21, 2025

View reviewed changes

Comment thread docs/INSTALL-CMAKE.md Outdated

phetdam added 2 commits February 22, 2025 22:43

INSTALL-CMAKE.md: fix CMake example indent + tweak wording

02e59f4

Merge branch 'master' into features/update-INSTALL-CMAKE

d466b18

docs/INSTALL-CMAKE.md: fix wording + use PRIVATE for CMake example

e3d8243

vszakats closed this in af0100f Feb 25, 2025


		$ cmake .

		Note, however, that it is recommended to build apart from the source tree, to

	Note, however, that it is recommended to build apart from the source tree, to
	It is recommended to build curl outside of the source tree, to

Uh oh!

Conversation

phetdam commented Feb 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

phetdam commented Feb 14, 2025

Uh oh!

bagder left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

bagder Feb 14, 2025

Choose a reason for hiding this comment

Uh oh!

phetdam Feb 16, 2025

Choose a reason for hiding this comment

Uh oh!

phetdam Feb 16, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vszakats Feb 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

phetdam Feb 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vszakats Feb 17, 2025

Choose a reason for hiding this comment

Uh oh!

phetdam Feb 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vszakats Feb 21, 2025

Choose a reason for hiding this comment

Uh oh!

phetdam Feb 23, 2025

Choose a reason for hiding this comment

Uh oh!

phetdam commented Feb 17, 2025

Uh oh!

Uh oh!

vszakats commented Feb 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

phetdam commented Feb 23, 2025

Uh oh!

vszakats commented Feb 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

phetdam commented Feb 25, 2025

Uh oh!

phetdam commented Feb 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vszakats commented Feb 25, 2025

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

phetdam commented Feb 14, 2025 •

edited

Loading

vszakats Feb 14, 2025 •

edited

Loading

phetdam Feb 16, 2025 •

edited

Loading

phetdam Feb 19, 2025 •

edited

Loading

vszakats commented Feb 21, 2025 •

edited

Loading

vszakats commented Feb 24, 2025 •

edited

Loading

phetdam commented Feb 25, 2025 •

edited

Loading