documentation: cross-compilation - partial rewrite #29418
Conversation
|
@vanschelven, thanks for your PR! By analyzing the history of the files in this pull request, we identified @Ericson2314 and @matthewbauer to be potential reviewers. |
|
@Ericson2314 @matthewbauer and others: Is there any way I can help to get this PR accepted? As it stands it's somewhat in limbo. |
|
Ah sorry, I forgot about it. The others probably left it to me as I single-handedly wrote what's there today. |
| @@ -11,7 +11,7 @@ | |||
| For example, a typical use of cross compilation is to compile programs for embedded devices. | |||
| These devices often don't have the computing power and memory to compile their own programs. | |||
| One might think that cross-compilation is a fairly niche concern, but there are advantages to being rigorous about distinguishing build-time vs run-time environments even when one is developing and deploying on the same machine. | |||
| Nixpkgs is increasingly adopting this opinion in that packages should be written with cross-compilation in mind, and nixpkgs should evaluate in a similar way (by minimizing cross-compilation-specific special cases) whether or not one is cross-compiling. | |||
| Nixpkgs is increasingly adopting the opinion that packages should be written with cross-compilation in mind, and nixpkgs should evaluate in a similar way (by minimizing cross-compilation-specific special cases) whether or not one is cross-compiling. | |||
doc/cross-compilation.xml
Outdated
| @@ -52,30 +52,33 @@ | |||
| <varlistentry> | |||
| <term><varname>hostPlatform</varname></term> | |||
| <listitem><para> | |||
| The "host platform" is the platform on which a package is run. | |||
| The "host platform" is the platform on which a package is to be run. | |||
doc/cross-compilation.xml
Outdated
| The target platform only applies to programming tools, and even then only is a good for for some of them. | ||
| Briefly, GCC, Binutils, GHC, and certain other tools are written in such a way such that a single build can only compile code for a single platform. | ||
| Thus, when building them, one must think ahead about which platforms they wish to use the tool to produce machine code for, and build binaries for each. | ||
| The "target platform" attribute is harder to understand. |
There was a problem hiding this comment.
It's not that its just hard to understand, but actually a flawed concept. It's hard to understand because it's bad, but not yet avoidable.
doc/cross-compilation.xml
Outdated
| <para> | ||
| A build time dependency, however, implies a shift in platforms between the depending package and the depended-on package. | ||
| The meaning of a build time dependency is that to build the depending package we need to be able to run the depended-on's package. | ||
| The depending package's build platform is thus reflected in the depended-on package's host platform. |
There was a problem hiding this comment.
"is thus reflected" -> "is". They are exactly equal.
vanschelven
force-pushed
the
small-documentation-improvements
branch
from
4ec70ee
to
fac7dba
Compare
|
@Ericson2314 I have integrated your remarks into a new (now squashed) commit. |
doc/cross-compilation.xml
Outdated
| The depending package's build platform is therefore equal to the depended-on package's host platform. | ||
| Analogously, the depending package's host platform is equal to the depended-on package's target platform. | ||
|
|
||
| In this manner, given the 3 platforms for one package, we can determine the three platforms for all its transitive build time dependencies. |
There was a problem hiding this comment.
I like the way that blank line snuck in :), maybe this should be its own pargraph?
There was a problem hiding this comment.
Then we can remove the "build time" you added because this final paragraph will be talking about all kinds of dependencies, not just build time ones.
vanschelven
force-pushed
the
small-documentation-improvements
branch
from
fac7dba
to
b20916b
Compare
|
@Ericson2314 I've included your last 2 nits in a final squashed commit. We should be good to go now! |
|
Oops, sorry! I saw you pushed and mistakenly thought I had merged already. Thanks again! |
Ericson2314
added
the
6.topic: cross-compilation
Motivation for this change
I personally had a hard time trying to understand what was being said in the cross-compilation section, and mentally rewrote some parts trying to figure it out.
When I finally did figure it out, I figured I might as well turn the understanding into a PR. I hope it is useful.