New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Doc clean up #50674
Doc clean up #50674
Conversation
doc/cross-compilation.xml
Outdated
built by a single build process. | ||
for a single platform. The task of specifying this single "target | ||
platform" is thus pushed to build time of the compiler. The root cause of | ||
this that the compiler (which will be run on the host) and the the |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
this that the compiler (which will be run on the host) and the the | |
this that the compiler (which will be run on the host) and the |
doc/cross-compilation.xml
Outdated
<link xlink:href="https://nixos.org/wiki/CrossCompiling" />, for this | ||
section. | ||
More information needs to be moved from the old wiki, especially <link | ||
xlink:href="https://nixos.org/wiki/CrossCompiling" />, for this section. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Dead link.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Tbh I would like to merge this right away, but a few small issues were introduced.
power and memory to compile their own programs. One might think that | ||
cross-compilation is a fairly niche concern. However, there are significant | ||
advantages to rigorously distinguishing between build-time and run-time | ||
environments! This applies even when one is developing and deploying on the |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Why is that?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Since this is an intro, I was going to leave the specifics out. We can put it somewhere else though. Basically:
- Make sure nativeBuildInputs don't end up in the package they built (via disallowedReferences)
- In addition we can avoid patching shebangs of things that shouldn't actually be needed at runtime.
- Make sure a package doesn't use buildInputs at build time (via PATH & HOST_PATH separation)
- With Adding pkgsStatic: a fully static overlay #48803, we can also use cross infrastructure to only override packages that are being built - not what is used to build them. This can be useful for lots of things. For instance, I want to use x version of bash with a package but don't want to rebuild my entire stdenv.
doc/cross-compilation.xml
Outdated
built by a single build process. | ||
for a single platform. The task of specifying this single "target | ||
platform" is thus pushed to build time of the compiler. The root cause of | ||
this that the compiler (which will be run on the host) and the the |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
the the
doc/cross-compilation.xml
Outdated
<literal>lib.systems.doubles</literal> for more. This format isn't very | ||
standard, but has built-in support in Nix, such as the | ||
<varname>builtins.currentSystem</varname> impure string. | ||
would be <literal>x86_64-darwin</literal> and |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The quotes do add value: the doubles are string values. Not names that refer to some attribute for example. Please add them back in.
called the "LLVM target triple", as they are pioneered by LLVM. In the | ||
4-part form, this corresponds to | ||
<literal>[cpu]-[vendor]-[os]-[abi]</literal>. This format is strictly | ||
more informative than the "Nix host double", as the previous format could | ||
analogously be termed. This needs a better name than | ||
<varname>config</varname>! |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Do we have an issue for this?
compiling. Because of this, a best-of-both-worlds solution is in the works | ||
with no splicing or explicit access of <varname>buildPackages</varname> | ||
needed. For now, feel free to use either method. | ||
How does this work in practice? Nixpkgs is now structured so that build-time |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
As a reference manual, it should describe the current situation and the current best practice. The current situation includes any technical debt, but it should be phrased as such and not like a change log.
doc/reviewing-contributions.xml
Outdated
pull-requests. Reviewing and approving these is an important task and a way | ||
to contribute to the project. | ||
</para> | ||
<para> | ||
The high change rate of nixpkgs makes any pull request that remains open for | ||
The high change rate of Nixpkgs makes any pull-request that remains open for |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
GitHub uses a space instead of a hyphen in "pull request"
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
These changes make it consistently pull-request
where it was a mix of them before. Not sure which is better.
doc/stdenv.xml
Outdated
depending derivation's platforms. Those offsets are given below in the | ||
descriptions of each dependency list attribute. Algorithmically, we traverse | ||
propagated inputs, accumulating every propagated dependency's propagated | ||
dependencys and adjusting them to account for the "shift in perspective" |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
dependencies
doc/stdenv.xml
Outdated
target offset from the new derivation's platforms. These are programs used | ||
at build time that produce code to run with code produced by the depending | ||
package. Most commonly, these are tools used to build the runtime or | ||
standard library taht the currently-being-built compiler will inject into |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
standard library taht the currently-being-built compiler will inject into | |
standard library that the currently-being-built compiler will inject into |
that can be used to see the <link | ||
xlink:href="https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc">most | ||
recently</link> and the <link | ||
xlink:href="https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-asc">least |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
An alternative is to use the browser extension refined-github, which does this sorting by default.
Imho small PRs work well for documentation. |
Haha yeah but this started out as a small PR :) I just found a lot more issues than I expected. |
This makes more sense in context.
This seems like a useful thing to document
Here I document setup hooks provided by: - cmake - xcbuildHook - meson - ninja - unzip - wafHook - scons
Lots of reworking here. May need to be split up.
xcbuild doesn’t work exactly like xcode in some ways.
More cleanups and stuff. May need to be split up.
This makes things more consistent. It’s also how GitHub refers to pull requests.
The link doesn’t work and it’s not very important to the documentation anyway.
5c26a54
to
c2e6a43
Compare
Thanks! There is still room for improvement, but these all should be good for now. |
Regression from NixOS#50674. Section IDs cannot contain spaces.
Motivation for this change
Some random doc cleanups I found. Mostly just rewording and typo fixes.