Merge pull request #106921 from siraben/platform-notes-md
stdenv/platform-notes: convert to markdown
This commit is contained in:
Jan Tojnar
GitHub
commit
f876a5df32
3 changed files with 63 additions and 84 deletions
|
|
@ -19,7 +19,7 @@
|
||||||
<xi:include href="stdenv/meta.xml" />
|
<xi:include href="stdenv/meta.xml" />
|
||||||
<xi:include href="stdenv/multiple-output.xml" />
|
<xi:include href="stdenv/multiple-output.xml" />
|
||||||
<xi:include href="stdenv/cross-compilation.chapter.xml" />
|
<xi:include href="stdenv/cross-compilation.chapter.xml" />
|
||||||
<xi:include href="stdenv/platform-notes.xml" />
|
<xi:include href="stdenv/platform-notes.chapter.xml" />
|
||||||
</part>
|
</part>
|
||||||
<part>
|
<part>
|
||||||
<title>Builders</title>
|
<title>Builders</title>
|
||||||
|
|
|
||||||
62
doc/stdenv/platform-notes.chapter.md
Normal file
62
doc/stdenv/platform-notes.chapter.md
Normal file
|
|
@ -0,0 +1,62 @@
|
||||||
|
# Platform Notes {#chap-platform-notes}
|
||||||
|
|
||||||
|
## Darwin (macOS) {#sec-darwin}
|
||||||
|
|
||||||
|
Some common issues when packaging software for Darwin:
|
||||||
|
|
||||||
|
- The Darwin `stdenv` uses clang instead of gcc. When referring to the compiler `$CC` or `cc` will work in both cases. Some builds hardcode gcc/g++ in their build scripts, that can usually be fixed with using something like `makeFlags = [ "CC=cc" ];` or by patching the build scripts.
|
||||||
|
|
||||||
|
```nix
|
||||||
|
stdenv.mkDerivation {
|
||||||
|
name = "libfoo-1.2.3";
|
||||||
|
# ...
|
||||||
|
buildPhase = ''
|
||||||
|
$CC -o hello hello.c
|
||||||
|
'';
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- On Darwin, libraries are linked using absolute paths, libraries are resolved by their `install_name` at link time. Sometimes packages won’t set this correctly causing the library lookups to fail at runtime. This can be fixed by adding extra linker flags or by running `install_name_tool -id` during the `fixupPhase`.
|
||||||
|
|
||||||
|
```nix
|
||||||
|
stdenv.mkDerivation {
|
||||||
|
name = "libfoo-1.2.3";
|
||||||
|
# ...
|
||||||
|
makeFlags = lib.optional stdenv.isDarwin "LDFLAGS=-Wl,-install_name,$(out)/lib/libfoo.dylib";
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- Even if the libraries are linked using absolute paths and resolved via their `install_name` correctly, tests can sometimes fail to run binaries. This happens because the `checkPhase` runs before the libraries are installed.
|
||||||
|
|
||||||
|
This can usually be solved by running the tests after the `installPhase` or alternatively by using `DYLD_LIBRARY_PATH`. More information about this variable can be found in the *dyld(1)* manpage.
|
||||||
|
|
||||||
|
```
|
||||||
|
dyld: Library not loaded: /nix/store/7hnmbscpayxzxrixrgxvvlifzlxdsdir-jq-1.5-lib/lib/libjq.1.dylib
|
||||||
|
Referenced from: /private/tmp/nix-build-jq-1.5.drv-0/jq-1.5/tests/../jq
|
||||||
|
Reason: image not found
|
||||||
|
./tests/jqtest: line 5: 75779 Abort trap: 6
|
||||||
|
```
|
||||||
|
|
||||||
|
```nix
|
||||||
|
stdenv.mkDerivation {
|
||||||
|
name = "libfoo-1.2.3";
|
||||||
|
# ...
|
||||||
|
doInstallCheck = true;
|
||||||
|
installCheckTarget = "check";
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- Some packages assume xcode is available and use `xcrun` to resolve build tools like `clang`, etc. This causes errors like `xcode-select: error: no developer tools were found at '/Applications/Xcode.app'` while the build doesn’t actually depend on xcode.
|
||||||
|
|
||||||
|
```nix
|
||||||
|
stdenv.mkDerivation {
|
||||||
|
name = "libfoo-1.2.3";
|
||||||
|
# ...
|
||||||
|
prePatch = ''
|
||||||
|
substituteInPlace Makefile \
|
||||||
|
--replace '/usr/bin/xcrun clang' clang
|
||||||
|
'';
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The package `xcbuild` can be used to build projects that really depend on Xcode. However, this replacement is not 100% compatible with Xcode and can occasionally cause issues.
|
||||||
|
|
@ -1,83 +0,0 @@
|
||||||
<chapter xmlns="http://docbook.org/ns/docbook"
|
|
||||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
||||||
xml:id="chap-platform-notes">
|
|
||||||
<title>Platform Notes</title>
|
|
||||||
<section xml:id="sec-darwin">
|
|
||||||
<title>Darwin (macOS)</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Some common issues when packaging software for Darwin:
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<itemizedlist>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The Darwin <literal>stdenv</literal> uses clang instead of gcc. When referring to the compiler <varname>$CC</varname> or <command>cc</command> will work in both cases. Some builds hardcode gcc/g++ in their build scripts, that can usually be fixed with using something like <literal>makeFlags = [ "CC=cc" ];</literal> or by patching the build scripts.
|
|
||||||
</para>
|
|
||||||
<programlisting>
|
|
||||||
stdenv.mkDerivation {
|
|
||||||
name = "libfoo-1.2.3";
|
|
||||||
# ...
|
|
||||||
buildPhase = ''
|
|
||||||
$CC -o hello hello.c
|
|
||||||
'';
|
|
||||||
}
|
|
||||||
</programlisting>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
On Darwin, libraries are linked using absolute paths, libraries are resolved by their <literal>install_name</literal> at link time. Sometimes packages won't set this correctly causing the library lookups to fail at runtime. This can be fixed by adding extra linker flags or by running <command>install_name_tool -id</command> during the <function>fixupPhase</function>.
|
|
||||||
</para>
|
|
||||||
<programlisting>
|
|
||||||
stdenv.mkDerivation {
|
|
||||||
name = "libfoo-1.2.3";
|
|
||||||
# ...
|
|
||||||
makeFlags = lib.optional stdenv.isDarwin "LDFLAGS=-Wl,-install_name,$(out)/lib/libfoo.dylib";
|
|
||||||
}
|
|
||||||
</programlisting>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
Even if the libraries are linked using absolute paths and resolved via their <literal>install_name</literal> correctly, tests can sometimes fail to run binaries. This happens because the <varname>checkPhase</varname> runs before the libraries are installed.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
This can usually be solved by running the tests after the <varname>installPhase</varname> or alternatively by using <varname>DYLD_LIBRARY_PATH</varname>. More information about this variable can be found in the <citerefentry>
|
|
||||||
<refentrytitle>dyld</refentrytitle>
|
|
||||||
<manvolnum>1</manvolnum></citerefentry> manpage.
|
|
||||||
</para>
|
|
||||||
<programlisting>
|
|
||||||
dyld: Library not loaded: /nix/store/7hnmbscpayxzxrixrgxvvlifzlxdsdir-jq-1.5-lib/lib/libjq.1.dylib
|
|
||||||
Referenced from: /private/tmp/nix-build-jq-1.5.drv-0/jq-1.5/tests/../jq
|
|
||||||
Reason: image not found
|
|
||||||
./tests/jqtest: line 5: 75779 Abort trap: 6
|
|
||||||
</programlisting>
|
|
||||||
<programlisting>
|
|
||||||
stdenv.mkDerivation {
|
|
||||||
name = "libfoo-1.2.3";
|
|
||||||
# ...
|
|
||||||
doInstallCheck = true;
|
|
||||||
installCheckTarget = "check";
|
|
||||||
}
|
|
||||||
</programlisting>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
Some packages assume xcode is available and use <command>xcrun</command> to resolve build tools like <command>clang</command>, etc. This causes errors like <code>xcode-select: error: no developer tools were found at '/Applications/Xcode.app'</code> while the build doesn't actually depend on xcode.
|
|
||||||
</para>
|
|
||||||
<programlisting>
|
|
||||||
stdenv.mkDerivation {
|
|
||||||
name = "libfoo-1.2.3";
|
|
||||||
# ...
|
|
||||||
prePatch = ''
|
|
||||||
substituteInPlace Makefile \
|
|
||||||
--replace '/usr/bin/xcrun clang' clang
|
|
||||||
'';
|
|
||||||
}
|
|
||||||
</programlisting>
|
|
||||||
<para>
|
|
||||||
The package <literal>xcbuild</literal> can be used to build projects that really depend on Xcode. However, this replacement is not 100% compatible with Xcode and can occasionally cause issues.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</itemizedlist>
|
|
||||||
</section>
|
|
||||||
</chapter>
|
|
||||||
Loading…
Reference in a new issue