From dde20aa10a8a9cfbaa794742f83a9cd6f28beb21 Mon Sep 17 00:00:00 2001 From: Christopher Wellons Date: Tue, 20 Oct 2026 06:33:27 -0400 Subject: [PATCH] Ship manual pages Keep the pages that GCC, Binutils and others install, add GDB's, Make's and zstd's from their sources, and generate ctags, CMake and Ccache pages from their documentation in a new stage with docutils, Sphinx and asciidoctor. Aliases such as cc, g++ and vi get one-line .so stubs instead of copies. The build fails if any installed page is not roff. Co-Authored-By: Claude Opus 5.5 --- Dockerfile | 60 ++++++++++++++++++++++++++++++++++++----- README.md | 16 +++++++---- man/man1/c++.1 | 1 + man/man1/c89.1 | 1 + man/man1/c99.1 | 1 + man/man1/cc.1 | 1 + man/man1/ccache-g++.1 | 1 + man/man1/ccache-gcc.1 | 1 + man/man1/g++.1 | 1 + man/man1/gcc-ar.1 | 1 + man/man1/gcc-nm.1 | 1 + man/man1/gcc-ranlib.1 | 1 + man/man1/gunzip.1 | 1 + man/man1/gvim.1 | 1 + man/man1/mingw32-make.1 | 1 + man/man1/pkg-config.1 | 1 + man/man1/unzstd.1 | 1 + man/man1/vi.1 | 1 + man/man1/vim.1 | 1 + man/man1/vimtutor.1 | 1 + man/man1/zcat.1 | 1 + man/man1/zipinfo.1 | 1 + 22 files changed, 85 insertions(+), 11 deletions(-) create mode 100644 man/man1/c++.1 create mode 100644 man/man1/c89.1 create mode 100644 man/man1/c99.1 create mode 100644 man/man1/cc.1 create mode 100644 man/man1/ccache-g++.1 create mode 100644 man/man1/ccache-gcc.1 create mode 100644 man/man1/g++.1 create mode 100644 man/man1/gcc-ar.1 create mode 100644 man/man1/gcc-nm.1 create mode 100644 man/man1/gcc-ranlib.1 create mode 100644 man/man1/gunzip.1 create mode 100644 man/man1/gvim.1 create mode 100644 man/man1/mingw32-make.1 create mode 100644 man/man1/pkg-config.1 create mode 100644 man/man1/unzstd.1 create mode 100644 man/man1/vi.1 create mode 100644 man/man1/vim.1 create mode 100644 man/man1/vimtutor.1 create mode 100644 man/man1/zcat.1 create mode 100644 man/man1/zipinfo.1 diff --git a/Dockerfile b/Dockerfile index 3cd254b..fda2c7e 100644 --- a/Dockerfile +++ b/Dockerfile @@ -124,7 +124,8 @@ ADD --checksum=sha256:$CTAGS_SHA256 \ https://github.com/universal-ctags/ctags/archive/refs/tags/v$CTAGS_VERSION.tar.gz \ ctags-$CTAGS_VERSION.tar.gz RUN mkdir ctags \ - && tar xzf ctags-$CTAGS_VERSION.tar.gz -C ctags --strip-components=1 + && tar xzf ctags-$CTAGS_VERSION.tar.gz -C ctags --strip-components=1 \ + && echo $CTAGS_VERSION >ctags/.version FROM base AS dl-zstd ARG ZSTD_VERSION=1.5.7 \ @@ -175,6 +176,7 @@ ADD --checksum=sha256:$XXHASH_SHA256 \ xxHash-$XXHASH_VERSION.tar.gz RUN mkdir ccache \ && tar xJf ccache-$CCACHE_VERSION.tar.xz -C ccache --strip-components=1 \ + && echo $CCACHE_VERSION >ccache/.version \ && mkdir xxhash \ && tar xzf xxHash-$XXHASH_VERSION.tar.gz -C xxhash --strip-components=1 @@ -757,8 +759,11 @@ RUN (cd /dl/gdb \ CXXFLAGS="-O2 -D__MINGW_USE_VC2005_COMPAT -DPDC_WIDE -I/deps/include" \ LDFLAGS="-s -L/deps/lib $LARGE_ADDRESS_FLAG" \ && make MAKEINFO=true -j$(nproc) \ - && mkdir -p /out/bin \ - && cp gdb/.libs/gdb.exe gdbserver/gdbserver.exe /out/bin/ + && mkdir -p /out/bin /out/share/man/man1 /out/share/man/man5 \ + && cp gdb/.libs/gdb.exe gdbserver/gdbserver.exe /out/bin/ \ + && cp /dl/gdb/gdb/doc/gdb.1 /dl/gdb/gdb/doc/gdbserver.1 \ + /out/share/man/man1/ \ + && cp /dl/gdb/gdb/doc/gdbinit.5 /out/share/man/man5/ FROM cross AS build-make COPY --from=dl-make /dl/ /dl/ @@ -774,8 +779,9 @@ RUN (cd /dl/make \ CFLAGS="-std=gnu17 -O2" \ LDFLAGS="-s" \ && make -j$(nproc) \ - && mkdir -p /out/bin \ + && mkdir -p /out/bin /out/share/man/man1 \ && cp make.exe /out/bin/ \ + && cp /dl/make/doc/make.1 /out/share/man/man1/ \ && $ARCH-gcc -DEXE=make.exe -DCMD=make \ -Oz -fno-asynchronous-unwind-tables \ -Wl,--gc-sections -s -nostdlib \ @@ -881,8 +887,9 @@ RUN make -j$(nproc) -C programs zstd \ CC=$ARCH-gcc CFLAGS="-O2 $ZSTD_CLI_FLAGS" \ LDFLAGS="-s $LARGE_ADDRESS_FLAG" EXT=.exe \ $ZSTD_THREAD_FLAG \ - && mkdir -p /out/bin \ + && mkdir -p /out/bin /out/share/man/man1 \ && cp programs/zstd.exe /out/bin/ \ + && cp programs/zstd.1 /out/share/man/man1/ \ && $ARCH-gcc -DEXE=zstd.exe -DCMD=unzstd \ -Oz -fno-asynchronous-unwind-tables -Wl,--gc-sections -s -nostdlib \ -o /out/bin/unzstd.exe $PREFIX/src/alias.c -lkernel32 @@ -1131,6 +1138,36 @@ RUN if [ "$GCC_MULTILIB" = enable ]; then \ install-stubs install-plugins ; \ fi +# Manual pages that need documentation tools to generate: ctags (docutils), +# CMake (Sphinx), and ccache (asciidoctor). The tools stay in this stage. +FROM base AS docs +RUN apt-get update \ + && apt-get install --yes --no-install-recommends \ + asciidoctor python3-docutils python3-sphinx \ + && rm -rf /var/lib/apt/lists/* +COPY --from=dl-ctags /dl/ctags /dl/ctags +COPY --from=dl-cmake /dl/cmake /dl/cmake +COPY --from=dl-ccache /dl/ccache /dl/ccache +RUN mkdir -p /out/share/man/man1 /out/share/man/man5 /out/share/man/man7 \ + && version=$(cat /dl/ctags/.version) \ + && for f in /dl/ctags/man/*.rst.in; do \ + page=$(basename $f .rst.in) \ + && case $page in readtags.1) continue;; esac \ + && rst2man --syntax-highlight=none $f \ + | sed -e s/@CTAGS_NAME_EXECUTABLE@/ctags/g \ + -e s/@ETAGS_NAME_EXECUTABLE@/etags/g \ + -e s/@VERSION@/$version/g \ + >/out/share/man/man${page##*.}/$page ; \ + done +RUN VERBOSE=1 cmake -S /dl/cmake/Utilities/Sphinx -B /x-cmake-doc -DSPHINX_MAN=ON \ + && VERBOSE=1 cmake --build /x-cmake-doc \ + && rm /x-cmake-doc/man/cmake-gui.1 \ + && cp /x-cmake-doc/man/*.1 /out/share/man/man1/ \ + && cp /x-cmake-doc/man/*.7 /out/share/man/man7/ +WORKDIR /dl/ccache +RUN bash doc/scripts/generate-manpage asciidoctor '' doc/ccache-doc.css \ + $(cat .version) doc/manual.adoc /out/share/man/man1/ccache.1 + # Collect source tarballs FROM base AS source COPY --from=dl-cross /dl/*.* /source/ @@ -1174,12 +1211,19 @@ COPY --from=build-cmake /out$PREFIX/ $PREFIX/ COPY --from=build-7z /dl/7z/7z.sfx /7z/ COPY --from=build-nsis /out$PREFIX/ $PREFIX/ COPY --from=build-aas-sign-w32 /out$PREFIX/ $PREFIX/ +COPY --from=docs /out/ $PREFIX/ COPY src $PREFIX/src COPY etc $PREFIX/etc WORKDIR / -RUN rm -rf $PREFIX/share/man/ $PREFIX/share/info/ $PREFIX/share/gcc-* +# Binutils installs pages for its ELF tools, which are removed above, and +# some installs leave empty section directories (man3). +RUN rm -rf $PREFIX/share/info/ $PREFIX/share/gcc-* \ + && rm $PREFIX/share/man/man1/readelf.1 $PREFIX/share/man/man1/elfedit.1 \ + && find $PREFIX/share/man -type d -empty -delete +# Hand-written pages, and alias stubs replacing installed copies (g++.1) +COPY man/man1/ $PREFIX/share/man/man1/ COPY README.md Dockerfile w64devkit.ini $PREFIX/ RUN printf "id ICON \"$PREFIX/src/w64devkit.ico\"" >w64devkit.rc \ && $ARCH-windres -o w64devkit.o w64devkit.rc \ @@ -1212,6 +1256,10 @@ RUN printf "id ICON \"$PREFIX/src/w64devkit.ico\"" >w64devkit.rc \ -lkernel32 -lshell32 -lmemory \ && $ARCH-gcc -nostartfiles -O2 -s -o $PREFIX/bin/nroff.exe \ $PREFIX/src/nroff.c -lmemory \ + && printf '.so man1/gcc.1\n' \ + >$PREFIX/share/man/man1/gcc-$($ARCH-gcc -dumpversion).1 \ + && ! grep -L -e '^\.TH' -e '^\.Dd' -e '^\.so ' $PREFIX/share/man/man*/* \ + | grep . \ && sed -i s/'\'/$ARCH/g $PREFIX/etc/profile \ && mkdir -p $PREFIX/lib/pkgconfig \ && cp /dl/mingw/COPYING.MinGW-w64-runtime/COPYING.MinGW-w64-runtime.txt \ diff --git a/README.md b/README.md index bd8dad2..1193532 100644 --- a/README.md +++ b/README.md @@ -129,9 +129,19 @@ later, does not implement recursive or timed locks, and just like MSVC, this handle to join or detach will trap. Also like MSVC, `mtx_t` and `cnd_t` support zero-initialization and their destructors are no-ops. +## Manual pages + +w64devkit includes manual pages for its commands: GCC, Binutils, GDB, +Make, CMake, Ccache, ctags, Vim, the BusyBox utilities, and w64devkit's +own tools. Read them with `man`, e.g. `man gcc` or `man 7 cmake-commands`, +including for prefixed names like `x86_64-w64-mingw32-ld`. Pages are +formatted by w64devkit's own `nroff`, which also displays pages that are +not installed: `man ./page.1`. Set `MANPATH` to add directories of your +own pages, organized like `share/man`. + ## Recommended downloadable, offline documentation -With a few exceptions, such as Vim's built-in documentation (`:help`), +Beyond its manual pages and Vim's built-in documentation (`:help`), w64devkit does not include documentation. However, you need not forgo offline documentation alongside your offline development tools. This is a list of recommended, no-cost, downloadable documentation complementing @@ -159,9 +169,6 @@ w64devkit's capabilities. In rough order of importance: * [GDB manual][doc-gdb] (PDF) -* [BusyBox man pages][doc-bb] (TXT), though everything here is also - available via `-h` option inside w64devkit. - * [Intel Software Developer Manuals][doc-intel] (PDF), for referencing x86 instructions, when either studying compiler output with `objdump` or writing assembly. @@ -264,7 +271,6 @@ binaries. [dcmake]: https://github.com/skeeto/dcmake [ctags]: https://github.com/universal-ctags/ctags [debugbreak]: https://nullprogram.com/blog/2022/07/31/ -[doc-bb]: https://busybox.net/downloads/BusyBox.txt [doc-cpp]: https://en.cppreference.com/w/Cppreference:Archives [doc-gcc]: https://gcc.gnu.org/onlinedocs/ [doc-gdb]: https://sourceware.org/gdb/current/onlinedocs/gdb.pdf diff --git a/man/man1/c++.1 b/man/man1/c++.1 new file mode 100644 index 0000000..a5be7bc --- /dev/null +++ b/man/man1/c++.1 @@ -0,0 +1 @@ +.so man1/gcc.1 diff --git a/man/man1/c89.1 b/man/man1/c89.1 new file mode 100644 index 0000000..a5be7bc --- /dev/null +++ b/man/man1/c89.1 @@ -0,0 +1 @@ +.so man1/gcc.1 diff --git a/man/man1/c99.1 b/man/man1/c99.1 new file mode 100644 index 0000000..a5be7bc --- /dev/null +++ b/man/man1/c99.1 @@ -0,0 +1 @@ +.so man1/gcc.1 diff --git a/man/man1/cc.1 b/man/man1/cc.1 new file mode 100644 index 0000000..a5be7bc --- /dev/null +++ b/man/man1/cc.1 @@ -0,0 +1 @@ +.so man1/gcc.1 diff --git a/man/man1/ccache-g++.1 b/man/man1/ccache-g++.1 new file mode 100644 index 0000000..bcb5001 --- /dev/null +++ b/man/man1/ccache-g++.1 @@ -0,0 +1 @@ +.so man1/ccache.1 diff --git a/man/man1/ccache-gcc.1 b/man/man1/ccache-gcc.1 new file mode 100644 index 0000000..bcb5001 --- /dev/null +++ b/man/man1/ccache-gcc.1 @@ -0,0 +1 @@ +.so man1/ccache.1 diff --git a/man/man1/g++.1 b/man/man1/g++.1 new file mode 100644 index 0000000..a5be7bc --- /dev/null +++ b/man/man1/g++.1 @@ -0,0 +1 @@ +.so man1/gcc.1 diff --git a/man/man1/gcc-ar.1 b/man/man1/gcc-ar.1 new file mode 100644 index 0000000..c2a62ca --- /dev/null +++ b/man/man1/gcc-ar.1 @@ -0,0 +1 @@ +.so man1/ar.1 diff --git a/man/man1/gcc-nm.1 b/man/man1/gcc-nm.1 new file mode 100644 index 0000000..dcd1a1f --- /dev/null +++ b/man/man1/gcc-nm.1 @@ -0,0 +1 @@ +.so man1/nm.1 diff --git a/man/man1/gcc-ranlib.1 b/man/man1/gcc-ranlib.1 new file mode 100644 index 0000000..a0dfc0f --- /dev/null +++ b/man/man1/gcc-ranlib.1 @@ -0,0 +1 @@ +.so man1/ranlib.1 diff --git a/man/man1/gunzip.1 b/man/man1/gunzip.1 new file mode 100644 index 0000000..c2a5145 --- /dev/null +++ b/man/man1/gunzip.1 @@ -0,0 +1 @@ +.so man1/gzip.1 diff --git a/man/man1/gvim.1 b/man/man1/gvim.1 new file mode 100644 index 0000000..f29b727 --- /dev/null +++ b/man/man1/gvim.1 @@ -0,0 +1 @@ +.so man1/vim.1 diff --git a/man/man1/mingw32-make.1 b/man/man1/mingw32-make.1 new file mode 100644 index 0000000..42f8e74 --- /dev/null +++ b/man/man1/mingw32-make.1 @@ -0,0 +1 @@ +.so man1/make.1 diff --git a/man/man1/pkg-config.1 b/man/man1/pkg-config.1 new file mode 100644 index 0000000..f706800 --- /dev/null +++ b/man/man1/pkg-config.1 @@ -0,0 +1 @@ +.so man1/u-config.1 diff --git a/man/man1/unzstd.1 b/man/man1/unzstd.1 new file mode 100644 index 0000000..d6b1713 --- /dev/null +++ b/man/man1/unzstd.1 @@ -0,0 +1 @@ +.so man1/zstd.1 diff --git a/man/man1/vi.1 b/man/man1/vi.1 new file mode 100644 index 0000000..f29b727 --- /dev/null +++ b/man/man1/vi.1 @@ -0,0 +1 @@ +.so man1/vim.1 diff --git a/man/man1/vim.1 b/man/man1/vim.1 new file mode 100644 index 0000000..0f00c83 --- /dev/null +++ b/man/man1/vim.1 @@ -0,0 +1 @@ +.so ../vim/doc/vim.1 diff --git a/man/man1/vimtutor.1 b/man/man1/vimtutor.1 new file mode 100644 index 0000000..d4dfbf4 --- /dev/null +++ b/man/man1/vimtutor.1 @@ -0,0 +1 @@ +.so ../vim/doc/vimtutor.1 diff --git a/man/man1/zcat.1 b/man/man1/zcat.1 new file mode 100644 index 0000000..c2a5145 --- /dev/null +++ b/man/man1/zcat.1 @@ -0,0 +1 @@ +.so man1/gzip.1 diff --git a/man/man1/zipinfo.1 b/man/man1/zipinfo.1 new file mode 100644 index 0000000..08bb928 --- /dev/null +++ b/man/man1/zipinfo.1 @@ -0,0 +1 @@ +.so man1/unzip.1