doc/manual/stdenv: improve cmake documentation #103506
Conversation
jonringer
added
the
9.needs: port to stable
doc/stdenv/stdenv.xml
Outdated
| <varlistentry> | ||
| <term> | ||
| cmake | ||
| <anchor xml:id="cmake"/> |
There was a problem hiding this comment.
You can add xml:id attribute directly to term element.
There was a problem hiding this comment.
yea, I thought about that after I created the PR
There was a problem hiding this comment.
do you know of a way that i can get the "link" element without using a section?
There was a problem hiding this comment.
What do you mean by using a section?
You can make any element linkable by adding xlink:href="#targetid attribute, or if you want to linkify arbitrary text, wrap it with <link> element and add the xlink:href argument to that. Or if you want to automatically generate the link title, use <xref linkend="targetid" /> – that should work for chapter, sections, tables, terms…
There was a problem hiding this comment.
I meant like https://nixos.org/manual/nixpkgs/stable/#chap-overlays where if you hover over the text, it will give you a "link" to that location
There was a problem hiding this comment.
xlink:href might work though, as that will at least make the text a link. better than the anchor to nowhere at least
There was a problem hiding this comment.
Oh, right, we do not have that. Maybe I could try to write a XSL transformation later but not sure if it is worth the effort with impending markdownification. For now, I just use developer tools to get the anchor links. And there are probably browser extensions that can make it easier too,
| </term> | ||
| <listitem> | ||
| <para> | ||
| Overrides the default configure phase to run the CMake command. By default, we use the Make generator of CMake. In addition, dependencies are added automatically to CMAKE_PREFIX_PATH so that packages are correctly detected by CMake. Some additional flags are passed in to give similar behavior to configure-based packages. You can disable this hook’s behavior by setting configurePhase to a custom value, or by setting dontUseCmakeConfigure. cmakeFlags controls flags passed only to CMake. By default, parallel building is enabled as CMake supports parallel building almost everywhere. When Ninja is also in use, CMake will detect that and use the ninja generator. | ||
| Overrides the default configure phase to run the CMake command. By default, we use the Make generator of CMake, however, if ninja is present, then the ninja generator will be used instead. In addition, dependencies are added automatically to CMAKE_PREFIX_PATH so that packages are correctly detected by CMake. By default, the cmake configurePhase can be thought of as: |
There was a problem hiding this comment.
It would be nice to add envar and literal tags where appropriate.
doc/stdenv/stdenv.xml
Outdated
| <title>Variables controlling CMake</title> | ||
| <varlistentry> | ||
| <term> | ||
| <varname>cmakeFlags</varname> |
There was a problem hiding this comment.
It might be also nice to add anchors to the individual variables – I did that for most of stdenv in 3f2b7be but somehow missed Meson, which was annoying when I wanted to link it recently.
|
@jtojnar just a reminder, I'm just trying to improve the documentation, not necessarily making it perfect :) |
| </term> | ||
| <listitem> | ||
| <para> | ||
| Overrides the default configure phase to run the CMake command. By default, we use the Make generator of CMake. In addition, dependencies are added automatically to CMAKE_PREFIX_PATH so that packages are correctly detected by CMake. Some additional flags are passed in to give similar behavior to configure-based packages. You can disable this hook’s behavior by setting configurePhase to a custom value, or by setting dontUseCmakeConfigure. cmakeFlags controls flags passed only to CMake. By default, parallel building is enabled as CMake supports parallel building almost everywhere. When Ninja is also in use, CMake will detect that and use the ninja generator. | ||
| Overrides the default configure phase to run the CMake command. By default, we use the Make generator of CMake, however, if ninja is present, then the ninja generator will be used instead. In addition, dependencies are added automatically to CMAKE_PREFIX_PATH so that packages are correctly detected by CMake. By default, the cmake configurePhase can be thought of as: |
There was a problem hiding this comment.
I think it's still worthwhile mentioning somewhere in the section that enableParallelBuilding = true by default for CMake, since there are still regularly PRs with enableParallelBuilding = true when the derivation uses CMake.
|
if someone with more docbook knowledge than me would like to take up this PR then please do so. but to be honest, I don't want to put in the time to learn docbook (nixpkgs is the only ecosystem I contribute to which uses it, and it's significantly different). I really want to improve documentation, but I really don't want to touch nixpkgs' documentation (docbook). I'll just wait for the commonmark conversion to start happening, and contribute then. |
|
If someone wants to adopt this, we also have a visual DocBook editor packaged: #95593 |
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/gnu-guix-1-2-0-released-2020-blog-gnu-guix/10167/5 |
erictapen
removed
the
9.needs: port to stable
|
@jonringer stdenv is now in markdown so you might want to revisit this. |
Motivation for this change
closes: #102104
Changes:
modeled it after the meson section
since stable manual is the default one on the website, this should also be backported.
Things done
sandboxinnix.confon non-NixOS linux)nix-shell -p nixpkgs-review --run "nixpkgs-review wip"./result/bin/)nix path-info -Sbefore and after)