Doc clean up #50674

matthewbauer · 2018-11-19T05:24:32Z

Motivation for this change

Some random doc cleanups I found. Mostly just rewording and typo fixes.

Mic92 · 2018-11-19T16:05:54Z

doc/cross-compilation.xml

-       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


Suggested change

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

Mic92 · 2018-11-19T16:09:25Z

doc/cross-compilation.xml

-    <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.


roberth

Tbh I would like to merge this right away, but a few small issues were introduced.

roberth · 2018-11-19T14:22:58Z

doc/cross-compilation.xml

+   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


Why is that?

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.

roberth · 2018-11-19T14:24:12Z

doc/cross-compilation.xml

-       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


roberth · 2018-11-19T14:26:57Z

doc/cross-compilation.xml

-       <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


The quotes do add value: the doubles are string values. Not names that refer to some attribute for example. Please add them back in.

roberth · 2018-11-19T14:28:40Z

doc/cross-compilation.xml

+       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>!


Do we have an issue for this?

roberth · 2018-11-19T14:32:56Z

doc/cross-compilation.xml

-    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


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.

roberth · 2018-11-19T15:57:15Z

doc/reviewing-contributions.xml

  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


GitHub uses a space instead of a hyphen in "pull request"

These changes make it consistently pull-request where it was a mix of them before. Not sure which is better.

roberth · 2018-11-19T15:58:25Z

doc/stdenv.xml

+   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"


dependencies

roberth · 2018-11-19T16:02:20Z

doc/stdenv.xml

+      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


Suggested change

standard library taht the currently-being-built compiler will inject into

standard library that the currently-being-built compiler will inject into

Mic92 · 2018-11-19T16:11:38Z

doc/reviewing-contributions.xml

+  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


An alternative is to use the browser extension refined-github, which does this sorting by default.

roberth · 2018-11-19T16:12:28Z

Imho small PRs work well for documentation.

matthewbauer · 2018-11-19T18:53:42Z

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.

matthewbauer · 2018-11-19T20:14:08Z

Thanks! There is still room for improvement, but these all should be good for now.

Regression from NixOS#50674. Section IDs cannot contain spaces.

GrahamcOfBorg added 8.has: documentation 10.rebuild-darwin: 0 10.rebuild-linux: 1-10 labels Nov 19, 2018

Mic92 reviewed Nov 19, 2018

View reviewed changes

roberth requested changes Nov 19, 2018

View reviewed changes

Mic92 reviewed Nov 19, 2018

View reviewed changes

matthewbauer added 9 commits November 19, 2018 13:02

doc: typo fixes

32ddbe3

doc: move checkInputs to check phase section

b01613c

This makes more sense in context.

doc/stdenv: document prefixKey

4621d14

This seems like a useful thing to document

doc/stdenv: document more setup hook

49e5bd0

Here I document setup hooks provided by: - cmake - xcbuildHook - meson - ninja - unzip - wafHook - scons

doc/stdenv: more changes

4a49921

Lots of reworking here. May need to be split up.

doc/platform-notes: reword xcode warning

ee58ab3

xcbuild doesn’t work exactly like xcode in some ways.

doc/cross-compilation: fixup

9d3108c

More cleanups and stuff. May need to be split up.

doc/reviewing-contributions: pull-requests -> pull requests

5e9f452

This makes things more consistent. It’s also how GitHub refers to pull requests.

doc/cross-compilation: remove reference to old wiki

c2e6a43

The link doesn’t work and it’s not very important to the documentation anyway.

matthewbauer force-pushed the proofing branch from 5c26a54 to c2e6a43 Compare November 19, 2018 19:03

matthewbauer merged commit 123da1f into NixOS:master Nov 19, 2018

delroth added a commit to delroth/nixpkgs that referenced this pull request Nov 20, 2018

doc/reviewing-contributions: fix build error

6b1d3dc

Regression from NixOS#50674. Section IDs cannot contain spaces.

delroth mentioned this pull request Nov 20, 2018

doc/reviewing-contributions: fix build error #50820

Merged

matthewbauer deleted the proofing branch February 22, 2019 04:22

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Doc clean up #50674

Doc clean up #50674

matthewbauer commented Nov 19, 2018

Mic92 Nov 19, 2018

Mic92 Nov 19, 2018

roberth left a comment

roberth Nov 19, 2018

matthewbauer Nov 19, 2018 •

edited

roberth Nov 19, 2018

roberth Nov 19, 2018

roberth Nov 19, 2018

roberth Nov 19, 2018

roberth Nov 19, 2018

matthewbauer Nov 19, 2018

roberth Nov 19, 2018

roberth Nov 19, 2018

Mic92 Nov 19, 2018

roberth commented Nov 19, 2018

matthewbauer commented Nov 19, 2018

matthewbauer commented Nov 19, 2018

	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

	standard library taht the currently-being-built compiler will inject into
	standard library that the currently-being-built compiler will inject into

Doc clean up #50674

Doc clean up #50674

Conversation

matthewbauer commented Nov 19, 2018

Motivation for this change

Choose a reason for hiding this comment

Choose a reason for hiding this comment

roberth left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

matthewbauer Nov 19, 2018 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

roberth commented Nov 19, 2018

matthewbauer commented Nov 19, 2018

matthewbauer commented Nov 19, 2018

matthewbauer Nov 19, 2018 •

edited