nix: generate man pages, update to 2.30.5. by JkktBkkt · Pull Request #60742 · void-linux/void-packages

JkktBkkt · 2026-05-25T05:49:16Z

As-is, running commands like nix-... --help or man nix-... or xmandoc nix-... doesn't provide any help or manual page. For some unbeknownst to me reason, the manual page works, i.e. https://man.voidlinux.org/man1/nix-build.1

A workaround is available: nix profile add nixpkgs#nix
However, not all installations use nix profiles.

A fix has been added to v2.34+ NixOS/nix#14952

Though building that version fails:

Details

[501/530] Generating src/nix-manual/manual with a custom command (wrapped by meson because command contains newlines, to set env)
FAILED: [code=101] src/nix-manual/manual src/nix-manual/markdown 
/usr/bin/meson --internal exe --unpickle /builddir/nix-2.34.7/build/meson-private/meson_exe_bash_01c3d0d0053814e6a2b214fe4dbb5d43c9f3a52c.dat
while executing ['/usr/bin/bash', '-euo', 'pipefail', '-c', '\n          /usr/bin/python3 ../src/nix-manual/generate-deps.py ../src/nix-manual > src/nix-manual/manual.d\n          /usr/bin/python3 ../src/nix-manual/substitute.py summary /builddir/nix-2.34.7/build/src/nix-manual < ../src/nix-manual/source/SUMMARY.md.in > /builddir/nix-2.34.7/build/src/nix-manual/source/SUMMARY.md\n          sed -e \'s|@version@|2.34.7|g\' < ../src/nix-manual/book.toml.in > /builddir/nix-2.34.7/build/src/nix-manual/book.toml\n          # Copy source to build directory, excluding the build directory itself\n          # (which is present when built as an individual component).\n          # Use tar with --dereference to copy symlink targets (e.g., JSON examples from tests).\n          (cd ../src/nix-manual && find . -mindepth 1 -maxdepth 1 ! -name build | tar -c --dereference -T - -f -) | (cd /builddir/nix-2.34.7/build/src/nix-manual && tar -xf -)\n          chmod -R u+w /builddir/nix-2.34.7/build/src/nix-manual\n          find /builddir/nix-2.34.7/build/src/nix-manual -name \'*.drv\' -delete\n          (cd /builddir/nix-2.34.7/build/src/nix-manual; RUST_LOG=warn /usr/bin/mdbook build -d /builddir/nix-2.34.7/build/src/nix-manual 3>&2 2>&1 1>&3) | { grep -Fv "because fragment resolution isn\'t implemented" || :; } 3>&2 2>&1 1>&3\n          rm -rf /builddir/nix-2.34.7/build/src/nix-manual/manual\n          mv /builddir/nix-2.34.7/build/src/nix-manual/html /builddir/nix-2.34.7/build/src/nix-manual/manual\n          # Remove Mathjax 2.7, because we will actually use MathJax 3.x\n          find /builddir/nix-2.34.7/build/src/nix-manual/manual | grep .html | xargs sed -i -e \'/2.7.1.MathJax.js/d\'\n          find /builddir/nix-2.34.7/build/src/nix-manual/manual -iname meson.build -delete\n      ']
--- stdout ---

--- stderr ---
 INFO Book building has started
substitute.py: INTERNAL ERROR in mdbook preprocessor: protocols/json/file-system-object-v1-fixed.md not found at /builddir/nix-2.34.7/build/src/nix-manual/source/protocols/json/file-system-object-v1-fixed.md
this is a bug in substitute.py
Traceback (most recent call last):
  File "/builddir/nix-2.34.7/build/src/nix-manual/./substitute.py", line 114, in <module>
    sys.exit(main())
             ~~~~^^
  File "/builddir/nix-2.34.7/build/src/nix-manual/./substitute.py", line 106, in main
    replaced_content = recursive_replace(book, book_root, search_path)
  File "/builddir/nix-2.34.7/build/src/nix-manual/./substitute.py", line 46, in recursive_replace
    items = [recursive_replace(item, book_root, search_path) for item in items],
             ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/builddir/nix-2.34.7/build/src/nix-manual/./substitute.py", line 69, in recursive_replace
    recursive_replace(sub_item, book_root, search_path)
    ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/builddir/nix-2.34.7/build/src/nix-manual/./substitute.py", line 69, in recursive_replace
    recursive_replace(sub_item, book_root, search_path)
    ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/builddir/nix-2.34.7/build/src/nix-manual/./substitute.py", line 56, in recursive_replace
    content = do_include(
              ~~~~~~~~~~^
        chapter_content,
        ^^^^^^^^^^^^^^^^
    ...<2 lines>...
        search_path
        ^^^^^^^^^^^
    ).replace(
    ^
  File "/builddir/nix-2.34.7/build/src/nix-manual/./substitute.py", line 32, in do_include
    assert included.exists(), f"{requested} not found at {included}"
           ~~~~~~~~~~~~~~~^^
AssertionError: protocols/json/file-system-object-v1-fixed.md not found at /builddir/nix-2.34.7/build/src/nix-manual/source/protocols/json/file-system-object-v1-fixed.md
ERROR The "substitute" preprocessor exited unsuccessfully with exit status: 1 status

And in cross as well, a bit earlier than that:

Details

[422/522] Generating src/nix-manual/source/store/types with a custom command (wrapped by meson to set env)
FAILED: [code=1] src/nix-manual/source/store/types 
env HOME=/dummy NIX_CONF_DIR=/dummy NIX_SSL_CERT_FILE=/dummy/no-ca-bundle.crt NIX_STATE_DIR=/dummy 'NIX_CONFIG=cores = 0' /usr/bin/python3 ../src/nix-manual/source/store/../../remove_before_wrapper.py src/nix-manual/source/store/types -- /builddir/nix-2.34.7/build/src/nix/nix --experimental-features nix-command eval -I nix=/builddir/nix-2.34.7/src/nix-manual --store dummy:// --impure --raw --expr 'import ../src/nix-manual/source/store/../../generate-store-types.nix (builtins.fromJSON (builtins.readFile ./src/nix-manual/nix.json)).stores'
Traceback (most recent call last):
  File "/builddir/nix-2.34.7/build/../src/nix-manual/source/store/../../remove_before_wrapper.py", line 33, in <module>
    main()
    ~~~~^^
  File "/builddir/nix-2.34.7/build/../src/nix-manual/source/store/../../remove_before_wrapper.py", line 27, in main
    subprocess.run(nix_command_write_to, check=True)
    ~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.14/subprocess.py", line 555, in run
    with Popen(*popenargs, **kwargs) as process:
         ~~~~~^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.14/subprocess.py", line 1039, in __init__
    self._execute_child(args, executable, preexec_fn, close_fds,
    ~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                        pass_fds, cwd, env,
                        ^^^^^^^^^^^^^^^^^^^
    ...<5 lines>...
                        gid, gids, uid, umask,
                        ^^^^^^^^^^^^^^^^^^^^^^
                        start_new_session, process_group)
                        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.14/subprocess.py", line 1990, in _execute_child
    raise child_exception_type(errno_num, err_msg, err_filename)
OSError: [Errno 8] Exec format error: '/builddir/nix-2.34.7/build/src/nix/nix'
[423/522] Generating src/nix-manual/source/command-ref/new-cli with a custom command (wrapped by meson to set env)
FAILED: [code=1] src/nix-manual/source/command-ref/new-cli 
env HOME=/dummy NIX_CONF_DIR=/dummy NIX_SSL_CERT_FILE=/dummy/no-ca-bundle.crt NIX_STATE_DIR=/dummy 'NIX_CONFIG=cores = 0' /usr/bin/python3 ../src/nix-manual/source/command-ref/../../remove_before_wrapper.py src/nix-manual/source/command-ref/new-cli -- /builddir/nix-2.34.7/build/src/nix/nix --experimental-features nix-command eval -I nix=/builddir/nix-2.34.7/src/nix-manual --store dummy:// --impure --raw --expr 'import ../src/nix-manual/source/command-ref/../../generate-manpage.nix true (builtins.readFile ./src/nix-manual/nix.json)'
Traceback (most recent call last):
  File "/builddir/nix-2.34.7/build/../src/nix-manual/source/command-ref/../../remove_before_wrapper.py", line 33, in <module>
    main()
    ~~~~^^
  File "/builddir/nix-2.34.7/build/../src/nix-manual/source/command-ref/../../remove_before_wrapper.py", line 27, in main
    subprocess.run(nix_command_write_to, check=True)
    ~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.14/subprocess.py", line 555, in run
    with Popen(*popenargs, **kwargs) as process:
         ~~~~~^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.14/subprocess.py", line 1039, in __init__
    self._execute_child(args, executable, preexec_fn, close_fds,
    ~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                        pass_fds, cwd, env,
                        ^^^^^^^^^^^^^^^^^^^
    ...<5 lines>...
                        gid, gids, uid, umask,
                        ^^^^^^^^^^^^^^^^^^^^^^
                        start_new_session, process_group)
                        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.14/subprocess.py", line 1990, in _execute_child
    raise child_exception_type(errno_num, err_msg, err_filename)
OSError: [Errno 8] Exec format error: '/builddir/nix-2.34.7/build/src/nix/nix'

So as a bit of a compromise, bump nix to latest 2.30.x release and enable building man pages.
These appear somewhat messy with all the md inclusions like: <../../command-ref/conf-file.md#command-line-flags>
But I do think it's better than nothing. Example excerpt:

Details

       The file manifest.nix <../command-ref/files/manifest.nix.md> is always
       ignored.

       The command nix-channel <../command-ref/nix-channel.md> places a
       symlink to the current user’s channels
       <../command-ref/files/channels.md> in this directory, the user channel
       link <#user-channel-link>.  This makes all subscribed channels
       available as attributes in the default expression.

   User channel link
       A symlink that ensures that nix-env <../command-ref/nix-env.md> can
       find the current user’s channels <../command-ref/files/channels.md>:

       •  ~/.nix-defexpr/channels
       •  $XDG_STATE_HOME/defexpr/channels if use-xdg-base-directories
          <../command-ref/conf-file.md#conf-use-xdg-base-directories> is set
          to true.

Testing the changes

I tested the changes in this PR: briefly

Local build testing

I built this PR locally for my native architecture, x86_64
I built this PR locally for these architectures (if supported. mark crossbuilds):
- x86_64-musl
- i686
- aarch64 *
- aarch64-musl *
- armv7l *
- armv7l-musl *
- armv6l *
- armv6l-musl *

nix: update to 2.30.5.

b57f72f

JkktBkkt force-pushed the nix-update branch from 91e7640 to b57f72f Compare May 25, 2026 14:41

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

nix: generate man pages, update to 2.30.5.#60742

nix: generate man pages, update to 2.30.5.#60742
JkktBkkt wants to merge 1 commit into
void-linux:masterfrom
JkktBkkt:nix-update

JkktBkkt commented May 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

JkktBkkt commented May 25, 2026

Testing the changes

Local build testing

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant