From: Karel Zak Date: Mon, 29 Jun 2026 11:54:10 +0000 (+0200) Subject: docs: replace howto-*.txt with HOWTO-*.md and add AGENTS.md X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=4d18877a660517e047348fcfdf6964440673a3e7;p=thirdparty%2Futil-linux.git docs: replace howto-*.txt with HOWTO-*.md and add AGENTS.md Replace the eight Documentation/howto-*.txt files with four consolidated markdown documents: HOWTO-BUILDING.md - compilation and build system internals HOWTO-CONTRIBUTING.md - contribution guidelines and PR workflow HOWTO-HACKING.md - usage functions, man pages, debugging HOWTO-TESTING.md - test framework, env variables, fuzz targets Add AGENTS.md to the project root with AI-specific coding guidance (code style pitfalls, return conventions, memory management, commit message format) and links to the new documentation files. Rename 00-about-docs.txt to 00-about-docs.md with updated references. Signed-off-by: Karel Zak --- diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..3d21d5e55e --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,78 @@ +# AGENTS.md + +This file provides guidance to AI coding agents working on this repository. + +util-linux is a collection of essential Linux system utilities and libraries +(libmount, libblkid, libsmartcols, libfdisk, libuuid). The project follows +Linux kernel coding conventions and workflows. + +## Legal + +Only human beings can be credited in commit messages. Do not include +Co-Developed-By, Co-Authored-By, or similar attribution for AI models. +Commits should include a Signed-off-by line (`git commit -s`). + +## Key Documentation + +Always consult these files as needed: + +- `Documentation/HOWTO-BUILDING.md` — how to compile the project, build system internals +- `Documentation/HOWTO-CONTRIBUTING.md` — contribution guidelines, patch and PR workflow +- `Documentation/HOWTO-HACKING.md` — coding details: usage functions, man pages, debugging +- `Documentation/HOWTO-TESTING.md` — regression test framework, environment variables + +## Code Style + +The coding style is based on the Linux kernel coding style. + +- Do NOT use `{ }` braces for single-line if/else blocks. +- Do not use `else` after non-returning functions (err(), errx(), exit(), ...). +- Avoid `if ((rc = func()) != 0)` — split into separate assignment and comparison: + ```c + rc = func(); + if (rc != 0) + ``` +- Use `printf()` consistently, not `fprintf(stdout, ...)`. +- Follow existing naming and coding conventions in each file. +- Use EditorConfig (`.editorconfig` in the project root) for whitespace settings. + +## Function Return Conventions + +- Boolean functions return true/false — name with `_is_`, `_has_`, `_can_`. +- Iterator `_next_` functions: 0 = success, <0 = error, 1 = end of list. +- Error-returning functions: negative errno or NULL. +- Check existing similar functions in libsmartcols, libmount for API consistency. + +## Memory Management + +- For non-library code, use `include/xalloc.h` wrappers (`xmalloc()`, `xcalloc()`, + `xstrdup()`, etc.) — these always succeed or terminate with `err()`. +- In libraries, check ownership semantics: does the function take ownership or copy? +- Trace every `malloc`/`calloc`/`strdup`/`asprintf` to its corresponding `free()`. +- `list_del()` must also free the element memory, not just unlink. +- Watch for missing `free()` on error/early-return paths. + +## Commit Messages + +- Use `Fixes:` when the commit resolves an issue. +- Use `Addresses:` when the commit only partly implements requested changes. +- Always use complete GitHub URLs, for example: + `Fixes: https://github.com/util-linux/util-linux/issues/NNN` +- Do not commit generated files (po/, po-man/, ./configure, ...). + +## Build and Test + +The project supports two build systems: autotools and meson. + +Autotools: + +- Build: `./autogen.sh && ./configure && make` +- Run tests: `make check` or `cd tests && ./run.sh` +- Selective build: `./configure --disable-all-programs --enable-` + +Meson: + +- Build: `meson setup build && meson compile -C build` +- Run tests: `meson test -C build` + +Features should include corresponding tests. diff --git a/Documentation/00-about-docs.md b/Documentation/00-about-docs.md new file mode 100644 index 0000000000..2312455f32 --- /dev/null +++ b/Documentation/00-about-docs.md @@ -0,0 +1,12 @@ +# About Documentation + +The util-linux Documentation/ directory contains supplementary material +such as readme files, release notes, and licenses. These files contain +information for contributors and should not end up in end-user installations. + +## Key Documents + +- [HOWTO-BUILDING.md](HOWTO-BUILDING.md) — how to compile the project, build system internals +- [HOWTO-CONTRIBUTING.md](HOWTO-CONTRIBUTING.md) — contribution guidelines, patch and PR workflow +- [HOWTO-HACKING.md](HOWTO-HACKING.md) — coding details: usage functions, man pages, debugging +- [HOWTO-TESTING.md](HOWTO-TESTING.md) — regression test framework, environment variables diff --git a/Documentation/00-about-docs.txt b/Documentation/00-about-docs.txt deleted file mode 100644 index b95ae44ca1..0000000000 --- a/Documentation/00-about-docs.txt +++ /dev/null @@ -1,7 +0,0 @@ -What is here ------------- - -The util-linux contains supplementary textual material, such as -readme files, release notes, licenses and so on. Common to these -files is that they contain information for contributors but -should not end up to end user installation. diff --git a/Documentation/HOWTO-BUILDING.md b/Documentation/HOWTO-BUILDING.md new file mode 100644 index 0000000000..1d436f358c --- /dev/null +++ b/Documentation/HOWTO-BUILDING.md @@ -0,0 +1,81 @@ +# Building util-linux + +## Quick Start + +Autotools: + + ./autogen.sh && ./configure && make + +If something fails, check the last lines — the typical reason is a missing +dependency such as libtool or gettext. + +Meson: + + meson setup build + meson compile -C build + +## Autotools Basics + +- `./autogen.sh` generates all files needed to compile (run after git checkout) +- `make distclean` removes generated files; code can still be recompiled + with `./configure && make` +- `make dist-gzip` (or `-bzip2`) creates a tarball that works without `./autogen.sh` + +## Selective Compilation + +See `./configure --help` for `--disable-*` and `--enable-*` options. + +Build only specific programs: + + ./configure --disable-all-programs --enable-fallocate + +The configure script tracks dependencies between libs and tools. Follow +warning/error messages. For example, mount(8) needs libmount, libblkid +and libuuid: + + ./configure --disable-all-programs --enable-mount \ + --enable-libmount --enable-libblkid --enable-libuuid + +## Compiler Flags + +Use `SUID_CFLAGS` and `SUID_LDFLAGS` for suid programs (chfn, chsh, +newgrp, su, write, mount, umount): + + ./configure SUID_CFLAGS="-fpie" SUID_LDFLAGS="-pie" + +Use `DAEMON_CFLAGS` and `DAEMON_LDFLAGS` for daemons (uuidd). + +Use `SOLIB_CFLAGS` and `SOLIB_LDFLAGS` for shared libraries (libmount, +libblkid, libuuid). + +## Static Linking + +Use `--enable-static-programs[=LIST]`. + +Note that mount(8) uses NSS functions (get{pw,gr}nam, getpwuid) which may +be dynamically loaded even in static builds. The UID/GID translation will +not work in environments where NSS modules are not installed. + +## Build System Internals + +The autotools build system is non-recursive — subdirectories use `Makemodule.am` +files that are merged by automake into one global Makefile. + +- All build results (binaries, libtool scripts) go in the top-level directory +- `Makemodule.am` files must use full paths (e.g., `foo_SOURCES = subdir/foo.c`) +- Always use `+=` for global variables (e.g., `bin_PROGRAMS += foo`) +- Use `libcommon.la` (without path) for lib/ stuff +- For libblkid/libuuid/libmount use `lib.la` in `_LDADD` and + `-I$(ul_lib_incdir)` in `_CFLAGS` +- Always use suffixes for hooks (e.g., `install-exec-hook-foo`) +- All autoconf macros use the `UL_` prefix +- Utils are enabled/disabled via `BUILD_` conditions (`AM_CONDITIONAL`) +- `BUILD_` blocks are never nested; dependencies are resolved in `configure.ac` + (see `UL_REQUIRES_BUILD()`) + +Predefined configure scenarios are in `tools/config-gen.d/`: + + ./tools/config-gen all selinux + +WARNING: `config-gen` is for development only, not for end-user or +downstream distribution builds. diff --git a/Documentation/HOWTO-CONTRIBUTING.md b/Documentation/HOWTO-CONTRIBUTING.md new file mode 100644 index 0000000000..1d2d6c5499 --- /dev/null +++ b/Documentation/HOWTO-CONTRIBUTING.md @@ -0,0 +1,118 @@ +# Contributing to util-linux + +## Repositories & Branches + +Primary repository: + + git clone git://git.kernel.org/pub/scm/utils/util-linux/util-linux.git + +GitHub (backup, pull requests, issue tracking): + + git clone https://github.com/util-linux/util-linux.git + +It's recommended to use github.com for development. + +Branches: + +- `master` — continuous development, never feature-frozen +- `stable/vX.Y` — stable releases, branched from master + +Since version 2.40, stabilization is done exclusively in `stable/` branches. + +## Sending Patches + +- Send patches via GitHub pull request (recommended) or to the mailing + list (see README). +- One patch per commit, many small patches preferred over a single large one. + Split by logical functionality. +- Do not include generated files (autotools, po/, po-man/). +- Do not include po/ translation changes — translations are maintained at + https://translationproject.org/domain/util-linux.html +- Patches must be distribution-neutral (no RPMs, DEBs, etc.). +- Alternatively, use `git format-patch` and `git send-email` to submit + patches to the mailing list (see README). + +## Commit Messages + +- Subject: `subsystem: description` +- Add a Signed-off-by line (`git commit -s`). +- Use `Fixes:` when the commit resolves an issue. +- Use `Addresses:` when the commit only partly implements requested changes. +- Always use complete GitHub URLs: + `Fixes: https://github.com/util-linux/util-linux/issues/NNN` + +## Pull Request Workflow + +1. Fork the repository on GitHub. + +2. Create a branch for your work (do not use `master` for contributions): + + git checkout master + git branch my-feature + git checkout my-feature + +3. Keep your branch up to date by rebasing on master: + + git fetch --all + git checkout master + git merge origin/master + git checkout my-feature + git rebase master + +4. Push and create a pull request: + + git push yourgit my-feature + +5. When resubmitting after review, incorporate reviewer comments and + force-push the updated branch: + + git rebase -i master + # fix things + git push -f yourgit my-feature + +6. After your branch is merged or rejected, clean up: + + git branch -d my-feature + git push yourgit :my-feature + +## Patching Process + +- Make sure the code compiles without errors or warnings. +- Test that existing behavior is not altered. If behavior changes + intentionally, explain what and why in the commit message. +- Only submit changes you believe are ready to merge. For review-only + patches, mark them as RFC. +- Incorporate reviewer comments before resubmitting. + +## Coding Style + +The preferred coding style is based on the Linux kernel coding style: +https://docs.kernel.org/process/coding-style.html + +- Use `FIXME:` with a description for known issues you are not fixing + in the current change. +- Do not use `else` after non-returning functions. +- When short if-else wraps to multiple lines, use the full `if () { } else { }` syntax. +- Consider installing an EditorConfig plugin (https://editorconfig.org/). + +## Options + +- Once options exist, they must not be changed, removed, or have their + behavior altered. +- `-h, --help` and `-V, --version` are reserved. +- Do not introduce new single-dash long options or non-standard option + characters. + +## Standards Compliance + +Some commands have Open Group / POSIX requirements: cal, col, ipcrm, +ipcs, kill, line, logger, mesg, more, newgrp, pg, renice. + +When modifying these, do not conflict with the latest standard. New short +options should not be added before they are part of the standard; +new long options are acceptable. + +## Various Notes + +- util-linux does not use kernel headers for filesystem super block structures. +- Patches relying on kernel features not in Linus Torvalds's tree are not accepted. diff --git a/Documentation/HOWTO-HACKING.md b/Documentation/HOWTO-HACKING.md new file mode 100644 index 0000000000..31d7c6be03 --- /dev/null +++ b/Documentation/HOWTO-HACKING.md @@ -0,0 +1,88 @@ +# Hacking on util-linux + +## Man Pages + +Since v2.37 util-linux uses asciidoc format for man pages. +See `man-common/manpage-stub.adoc` for details. + +## Usage Function + +Refer to `Documentation/boilerplate.c` for a complete example. + +### Format + +The `usage()` output consists of: Usage section, one-line command description, +Options section, optional special sections (e.g., 'Available columns'), and +a final man page reference line. Each section is separated by one empty line. + +Only the synopsis and option lines are indented (one space). +Option lines do not use line-ending punctuation. + +### Synopsis + +Diamond brackets `` mark required arguments, square brackets `[arg]` +mark optional ones. Optional option arguments require `=` with no whitespace: +`--optional[=]`. Three dots `...` indicate unlimited repetition. + +Use multiple synopsis lines when a command does fundamentally different things +depending on options/arguments: + + ionice [options] -p ... + ionice [options] [ ...] + +### Option Descriptions + +- Short option first, then long option, separated by comma and space. +- Description starts at the column of the longest option plus two spaces. +- Maximum width is 80 characters; use indented continuation lines if needed. +- `--help` and `--version` are always last. +- One gettext entry per option — be nice to translators. + +Use the `USAGE_HELP_OPTIONS()` macro from `include/c.h` for the +help/version options, where `` is the description start column. + +### Usage Function Rules + +- `usage()` never returns — it is only called by `-h`/`--help`. +- All other error cases use `errtryhelp(EXIT_FAILURE)`. +- Use string constants from `include/c.h` for section headers. + +## Debugging + +### Libtool Wrappers (autotools only) + +Binaries built with autotools/libtool are wrapped by shell scripts. The +actual binary is in `.libs/` (e.g., `mount/.libs/mount`). To run it +directly with gdb or valgrind, set `LD_LIBRARY_PATH`: + + export LD_LIBRARY_PATH=$PWD/libblkid/src/.libs/:$LD_LIBRARY_PATH + +Meson builds produce directly usable binaries without wrappers, so this +is not needed when building with meson. + +### Library Debug Output + +All libraries support debug output via environment variables: + + export LIBBLKID_DEBUG=all + export LIBMOUNT_DEBUG=all + export LIBFDISK_DEBUG=all + export LIBSMARTCOLS_DEBUG=all + +See `libblkid/src/blkidP.h` and `libmount/src/mountP.h` for the meaning +of individual debug flags. + +### Libmount Path Overrides + +These environment variables override default paths (ignored for non-root): + +| Variable | Default | +|---|---| +| `LIBMOUNT_FSTAB` | `/etc/fstab` | +| `LIBMOUNT_MTAB` | `/etc/mtab` | +| `LIBMOUNT_UTAB` | `/run/mount/utab` | + +### Libblkid Overrides + +- `BLKID_CONF` — override `/etc/blkid.conf` +- `BLKID_FILE` — override cache file location (see blkid(8)) diff --git a/Documentation/HOWTO-TESTING.md b/Documentation/HOWTO-TESTING.md new file mode 100644 index 0000000000..0503402842 --- /dev/null +++ b/Documentation/HOWTO-TESTING.md @@ -0,0 +1,85 @@ +# Testing util-linux + +## Quick Start + +Compile and run basic tests: + + make check + +Or with meson: + + meson test -C build + +Run all tests including those requiring root: + + # cd tests + # ./run.sh [options, see --help] + +Or using sudo with make: + + $ make check-programs + $ sudo -E make check TS_OPTS="--parallel=1" + +Note: as root you must manually remove output and diff directories +(`rm -rf output diff`) or run `make clean` as root. + +Note: the configure option `--disable-static` disables many libmount +and libblkid unit tests. + +## Running Specific Tests + +Run a test group: + + $ cd tests + $ ./run.sh blkid + $ ./run.sh libmount + +Run an individual test: + + $ ./ts/cal/year + +Exclude tests: + + $ ./run.sh --exclude="mount/move" + +## Compile Test Programs Only + + $ make check-programs + +## Fuzz Targets + +Build and run fuzz targets (requires clang): + + $ ./tools/config-gen fuzz + $ make check + +## Environment Variables + +`TS_COMMAND` — override the default command for `make check`: + + $ make check TS_COMMAND="true" # build deps only, skip tests + +`TS_OPTS` — pass options to `run.sh`: + + $ make check TS_OPTS="--parallel=1 utmp" + +`TS_OPT_testdir_[testscript_]fake="yes|no"` — skip tests: + + $ make check TS_OPT_fdisk_fake="yes" # skip all fdisk tests + $ make check TS_OPT_fdisk_bsd_fake="yes" # skip only fdisk/bsd + $ make check TS_OPT_fdisk_fake="yes" TS_OPT_fdisk_bsd_fake="no" # skip all fdisk except bsd + +`TS_OPT_testdir_[testscript_]known_fail="yes|no"` — mark tests as known +failures (test runs but negative results are ignored). + +`TS_OPT_testdir_[testscript_]verbose="yes|no"` — set verbosity. + +`TS_OPT_testdir_[testscript_]memcheck="yes|no"` — run with valgrind. + +## External Services + +- Coveralls: https://coveralls.io/github/util-linux/util-linux +- Coverity Scan: https://scan.coverity.com/projects/karelzak-util-linux +- Fossies codespell: https://fossies.org/linux/test/util-linux-master.tar.gz/codespell.html +- OSS-Fuzz: https://oss-fuzz.com/coverage-report/job/libfuzzer_asan_util-linux/latest +- CIFuzz: https://github.com/util-linux/util-linux/actions?query=workflow%3ACIFuzz diff --git a/Documentation/howto-build-sys.txt b/Documentation/howto-build-sys.txt deleted file mode 100644 index 46d2793a12..0000000000 --- a/Documentation/howto-build-sys.txt +++ /dev/null @@ -1,95 +0,0 @@ -util-linux build system -======================= - - - the build system is non-recursive, individual subdirectories use - Makemodule.am files. These files are merged together by automake - into one global Makefile in the top-level directory - - - all final build results (binaries, libtool scripts) are stored in top-level - source directory - - - all Makemodule.am files have to be designed as top-level makefiles, it - means with full paths (e.g. foo_SOURCES = subdir/foo.c) - - - always use '+=' operator for global variables (e.g. bin_PROGRAMS += foo) - - - use libcommon.la (without path!) for lib/ stuff (e.g. foo_LDADD = libcommon.la) - - - for libblkid, libuuid and libmount use lib.la in _LDADD and - -I$(ul_lib_incdir) in _CFLAGS, for example - - foo_LDADD = libmount.la - foo_CFLAGS = -I$(ul_libmount_incdir) - - - always use suffixes for hooks, for example - - install-exec-hook-foo: - ln -sf foo foooo - - INSTALL_EXEC_HOOKS += install-exec-hook-foo - - - - all util-linux specific autoconf macros use UL_ prefix - - - utils in Makefile.am files are enabled/disabled according to BUILD_ - conditions (AM_CONDITIONAL), for example: - - if BUILD_HWCLOCK - ... - endif - - - "if BUILD_" blocks are never nested within another "if BUILD_", - all dependencies have to be resolved in configure.ac (see UL_REQUIRES_BUILD()) - - - all BUILD_ in configure.am are always based on build_ variables, - for example: - - AM_CONDITIONAL([BUILD_HWCLOCK], test "x$build_hwclock" = xyes) - - the $build_ should be available in whole configure script - - - AC_ARG_ENABLE() status is always stored in $enable_ variable, possible - setting: - - "check" - util/feature is optional, if any subcomponent (function, lib, - ...) is missing a warning is printed and the util/feature is - disabled - - "yes" - util/feature is required, if any subcomponent (function, lib, - ...) is missing an error is printed and ./configure aborted - - "no" - the util/feature is unwanted - - The default status is always defined by UL_DEFAULT_ENABLE() and it might be - globally modified by $ul_default_estate (see AC_ARG_ENABLE([all-programs])). - - - it's possible to disable all programs, but enable just one (or more) - explicitly specified, for example: - - ./configure --disable-all-programs --enable-hwclock - - - some basic scenarios for the ./configure script are defined in the - tools/config-gen.d/ directory. If you want to use these predefined scenarios - then call - - ./tools/config-gen [ ...] - - for example - - ./tools/config-gen all selinux - - will build all utils with enabled selinux support. You can also define some - CFLAGS, for example: - - CFLAGS=$(rpm --eval '%optflags') ./tools/config-gen all - - will use the default distro flags. - - WARNING: config-gen is not designed for end-user or downstream distributions! - It's for development purpose only. All end-users and downstream have - to use standard ./configure script only. - - - the tools/config-gen script is also used for build system regression tests, - the test is not enabled by default, you have to use - - tests/run.sh build-sys --force diff --git a/Documentation/howto-compilation.txt b/Documentation/howto-compilation.txt deleted file mode 100644 index 6a86b303cc..0000000000 --- a/Documentation/howto-compilation.txt +++ /dev/null @@ -1,90 +0,0 @@ -The common case - - ./autogen.sh && ./configure && make - - If something fails read the last lines. Typical reason to - fail is a missing dependency, such as libtool or gettext. - - make install-strip - - Note that on the production systems it is strongly recommended to use - "make install-strip" to install binaries and libraries. The result - from the standard "make install" may produce large binaries with - unnecessary symbols. - -Autotools - - `./autogen.sh' generates all files needed to compile - and install the code (run it after checkout from git) - - `make distclean' removes all unnecessary files, but the - code can still be recompiled with "./configure; make" - - `make dist-gzip' (or -bzip2) creates a tarball that can - be configured and compiled without running `./autogen.sh' - -Compiling - - Use SUID_CFLAGS and SUID_LDFLAGS when you want to define - special compiler options for typical suid programs, for - example: - - ./configure SUID_CFLAGS="-fpie" SUID_LDFLAGS="-pie" - - The SUID_* feature is currently supported for chfn, chsh, - newgrp, su, write, mount, and umount. - - Use DAEMON_CFLAGS and DAEMON_LDFLAGS when you want to define - special compiler options for daemons; supported for uuidd. - - Use SOLIB_CFLAGS and SOLIB_LDFLAGS when you want to define - special compiler options for shared libraries; supported for - libmount, libblkid and libuuid. - - FIXME: add notes about klib and uClib. - - -Compile certain portion - - See ./configure --help and use --disable-* and --enable-* options. - - It's also possible to disable all the programs and enable only wanted. - For example: - - ./configure --disable-all-programs --enable-fallocate - - Note that the configure script tracks dependencies between libs and - tools. Always see warning messages and follow error messages if any - dependence is necessary. For example to compile mount(8) you need also - libmount, libblkid and libuuid: - - ./configure --disable-all-programs --enable-mount --enable-libmount \ - --enable-libblkid --enable-libuuid - - -Static linking - - Use --enable-static-programs[=LIST] configure option when - you want to use statically linked programs. - - Note, mount(8) uses get{pw,gr}nam() and getpwuid() - functions for translation from username and groupname to - UID and GID. These functions could be implemented by - dynamically loaded independent modules (NSS) in your libc - (e.g. glibc). These modules are not statically linked to - mount(8) and mount.static is still using dlopen() like - dynamically linked version. - - The translation won't work in environment where NSS - modules are not installed. - - For example normal system (NSS modules are available): - - # ./mount.static -v -f -n -ouid=kzak /mnt/foo - LABEL=/mnt/foo on /mnt/foo type vfat (rw,uid=500) - ^^^^^^^ - and without NSS modules: - - # chroot . ./mount.static -v -f -n -ouid=kzak /mnt/win - LABEL=/mnt/win on /mnt/win type vfat (rw,uid=kzak) - ^^^^^^^^ diff --git a/Documentation/howto-contribute.txt b/Documentation/howto-contribute.txt deleted file mode 100644 index 80c2e9f0a1..0000000000 --- a/Documentation/howto-contribute.txt +++ /dev/null @@ -1,253 +0,0 @@ -CONTENTS - Sending Patches - Patching Process - Email Format - Coding Style - Options - Various Notes - Standards Compliance - -Sending Patches - - * send your patches to the mailing list (see ../README) or by - github.com pull request. - - * email is accepted as an inline patch with, or without, a git pull - request. Pull request emails need to include the patch set for review - purposes. See howto-pull-request.txt and ../README for git repository - instructions. - - * email attachments are difficult to review and not recommended. - Hint: use git send-email. - - * one patch per email. - See Email Format. - - * many small patches are preferred over a single large patch. Split - patch sets based upon logical functionality. For example: #endif mark - ups, compiler warnings, and exit code fixes should all be individual - small patches. - - * don't include generated (autotools) files in your patches. - Hint: use 'git clean -Xd'. - - * don't include po/ (translations) changes to the upstream patches. - The po/ stuff is maintained on https://translationproject.org/domain/util-linux.html - and updated always before the next release. - - * neutrality: the files in util-linux should be distribution-neutral. - Packages like RPMs, DEBs, and the rest, are not provided. They should - be available from the distribution. - -Repositories & Branches - - * Primary repository is on kernel.org: - git clone git://git.kernel.org/pub/scm/utils/util-linux/util-linux.git - - * Backup repository at github.com: - git clone https://github.com/util-linux/util-linux.git - - We use this repository to backup kernel.org and for PULL REQUESTS, - issues tracking. The master and stable branches are always pushed to - the both repositories in the same time. - - It's recommended to use github.com for development. - - * Branches: - - master - continuous development - stable/vX.Y - stable releases - - Since version 2.40, the "master" branch remains continuously open and is - never subjected to feature freezes. The stabilization process for - the upcoming release is exclusively conducted within the "stable/" branches. - Upon branching from "master" to "stable/vX.Y," a new tag vX.Y+1-devel - is generated to serve as placeholder for git-based versioning (refer to - tools/git-version-gen). Subsequently, changes specific to the new release - (such as po/ updates) are selectively cherry-picked from "stable/vX.Y" to - "master" after the final release. - -Patching Process - - * announce it on the mailing list when you are going to work with some - particular piece of code for a long time. This helps others to avoid - massive merge conflicts. Small or quick work, does not need to be - announced. - - * make sure that after applying your patch the file(s) will compile - without errors. - - * test that the previously existing program behavior is not altered. If - the patch intentionally alters the behavior explain what changed, and - the reason for it, in the changelog/commit message. - - * only submit changes that you believe are ready to merge. To post a - patch for peer review only, state it clearly in the email and use - the Subject: [PATCH RFC] ... - - * incorporate reviewer comments in the patches. Resubmitting without - changes is neither recommended nor polite. - - * resubmission can be partial or complete. If only a few alterations are - needed then resubmit those particular patches. When comments cause a - greater effect then resubmit the entire patch set. - - * When resubmitting use the email Subject: [PATCH v2] ... - Hint: use the --subject-prefix='PATCH v2' option with 'git format-patch' - - * using a git repository for (re)submissions can make life easier. - See howto-pull-request.txt and ../README. - - * all patch submissions are either commented, rejected, or accepted. - If the maintainer rejects a patch set it is pointless to resubmit it. - -Email Format - - * Subject: [PATCH] subsystem: description. - - * Start the message body with an explanation of the patch, that is, a - changelog/commit entry. - - * if someone else wrote the patch, they should be credited (and - blamed) for it. To communicate this, add a line like: - - From: John Doe - - * add a Signed-off-by line. - Hint: use git commit -s - - The sign-off is a simple line at the end of the explanation for the - patch; which certifies that you wrote it or otherwise have the - right to pass it on as an open-source patch. The rules are pretty - simple; if you can certify the following: - - By making a contribution to this project, I certify that: - - (a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - - (b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - - (c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - - (d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including - all personal information I submit with it, including my - sign-off) is maintained indefinitely and may be redistributed - consistent with this project or the open source license(s) - involved. - - Then you just add a line like: - - Signed-off-by: Random J Developer - - Use your real name (sorry, no pseudonyms or anonymous contributions.) - - * Next a single line beginning with three hyphen-minus characters (---) - and nothing else. - - * Followed by the unified diff patch. - - Note: the mailing list will reject certain content. See ../README. - -Coding Style - - * the preferred coding style is based on the linux kernel coding-style. - Available here: - - https://docs.kernel.org/process/coding-style.html - - * use 'FIXME:' with a good description, if you want to inform others - that something is not quite right, and you are unwilling to fix the - issue in the submitted change. - - * do not use `else' after non-returning functions. For - example: - - if (this) - err(EXIT_FAIL, "this failed"); - else - err(EXIT_FAIL, "that failed"); - - Is wrong and should be written: - - if (this) - err(EXIT_FAIL, "this failed"); - err(EXIT_FAIL, "that failed"); - - * when you use 'if' short-shorthand make sure it does not wrap into - multiple lines. In case the shorthand does not look good on one line - use the normal "if () else" syntax. - - * To avoid whitespace errors, consider installing an EditorConfig plugin - (https://editorconfig.org/) into your favorite editor or IDE. - -Options - - * The rule of thumb for options is that once they exist, you may not - change them, nor change how they work, nor remove them. - - * The following options are well-known, and should not be used for any - other purpose: - - -h, --help display usage and exit - -V, --version display version and exit - - * Some commands use peculiar options and arguments. These will continue - to be supported, but anything like them will not be accepted as new - additions. A short list of examples: - - Characters other than '-' to start an option. See '+' in 'more'. - - Using a number as an option. See '-' in 'more'. - - Long options that start with a single '-'. See 'setterm'. - - '-?' is not a synonym for '--help', but is an unknown option - resulting in a suggestion to try --help due to a getopt failure. - -Various Notes - - * util-linux does not use kernel headers for file system super - blocks structures. - - * patches relying on kernel features that are not in Linus Torvalds's - tree are not accepted. - -Standards Compliance - - Some of the commands maintained in this package have Open Group - requirements. These commands are: - - cal - col - ipcrm - ipcs - kill - line - logger - mesg - more - newgrp - pg - renice - - If you change these tools please make sure it does not create a conflict - with the latest standard. For example, it is not recommended to add - short command line options before they are part of the standard. - Introducing new long options is acceptable. - - The Single UNIX(TM) Specification, Version 2 - Copyright (C) 1997 The Open Group - - https://pubs.opengroup.org/onlinepubs/7908799/xcuix.html - diff --git a/Documentation/howto-debug.txt b/Documentation/howto-debug.txt deleted file mode 100644 index 6936eb54d4..0000000000 --- a/Documentation/howto-debug.txt +++ /dev/null @@ -1,74 +0,0 @@ -Debugging util-linux programs -============================= - -How to deal libtool -------------------- - -There are considerations to be made when profiling or debugging some programs -found in the util-linux package. Because wrapper scripts are used for the -binaries to make sure all library dependencies are met, you cannot use tools -such as gdb or valgrind directly with them. - -Let's take for example the mount command: - - $> cd /path/to/util-linux - $> file mount/mount - mount/mount: Bourne-Again shell script text executable - -The binary itself is located in the mount/.libs/ directory: - - $> file mount/.libs/mount - mount/.libs/mount: ELF 64-bit LSB executable, x86-64, version 1 \ - (SYSV), dynamically linked (uses shared libs) [...] - -When this command is run, there's a library dependency error: - - $> mount/.libs/mount - mount/.libs/mount: /lib/libblkid.so.1: version `BLKID_2.20' not found \ - (required by mount/.libs/mount) - -To overcome this we need set the LD_LIBRARY_PATH variable to read the path of -the shared lib found in the sources, and not system-wide: - - $> export LD_LIBRARY_PATH=$PWD/libblkid/src/.libs/:$LD_LIBRARY_PATH - -Now external debugging tools can be run on the binary. - -Happy hacking! -Davidlohr Bueso, August 2011 - - -The libmount & libblkid ------------------------ - -Both of the libraries can be debugged by setting an environment variable -consisting of a number. The number will be used as a bit mask, so the more 1 the -higher the debugging level. Search for `DEBUG' from files - - libblkid/src/blkidP.h - libmount/src/mountP.h - -to see what the different bits mean. At the time of writing this the following -enabled full debug. - - export LIBBLKID_DEBUG=all - export LIBMOUNT_DEBUG=all - export LIBFDISK_DEBUG=all - export LIBSMARTCOLS_DEBUG=all - -The libblkid reads by default /etc/blkid.conf which can be overridden by the -environment variable BLKID_CONF. See manual libblkid/libblkid.3 for details -about the configuration file. - -Block device information is normally kept in a cache file (see blkid man page -for more information about the cache file location) that can be overridden by -the environment variable BLKID_FILE. - -To libmount uses three paths, which can be overridden by using environment -variables. Notice that these environment variables are ignored for non-root -users. - - env variable if not set defaults to - LIBMOUNT_FSTAB /etc/fstab - LIBMOUNT_MTAB /etc/mtab - LIBMOUNT_UTAB /run/mount/utab or /dev/.mount/utab diff --git a/Documentation/howto-man-page.txt b/Documentation/howto-man-page.txt deleted file mode 100644 index d0ebd01bab..0000000000 --- a/Documentation/howto-man-page.txt +++ /dev/null @@ -1,2 +0,0 @@ -Since v2.37 util-linux project uses asciidoc format to maintain man pages. -See man-common/manpage-stub.adoc for more details. diff --git a/Documentation/howto-pull-request.txt b/Documentation/howto-pull-request.txt deleted file mode 100644 index 0a4fb94e30..0000000000 --- a/Documentation/howto-pull-request.txt +++ /dev/null @@ -1,290 +0,0 @@ -Introduction ------------- - -These instructions are written for contributors who tend to send lots of -changes. The basics from the howto-contribute.txt file are assumed to be -read and understood by the time this file becomes useful. - -In these instructions, the upstream remote repository is called -'origin' and 'yourgit' is the contributor repository. - -Setup ------ - -1. Find a git server that can be reached from anywhere on the internet -anonymously. Github, for example, is a popular choice. - -2. Create your own util-linux contributor repository, and push an upstream -clone there: - -cd ~/projects -git clone git://git.kernel.org/pub/scm/utils/util-linux/util-linux.git -cd util-linux -git remote add yourgit git@github.com:yourlogin/util-linux.git -git push yourgit - - -Branches --------- - -1. The name of your branch isn't crucial, but if you intend to contribute -regularly, it's beneficial to establish a naming convention that works well for -you. For instance, consider prefixing your branch name with the subsystem's -name, such as blkid, libmount, etc. - -2. Avoid using the 'master' branch for your contributions. The 'master' branch -should be reserved for staying synchronized with the upstream repository. - -3. Once you've completed your work, push your branch to your remote Git server: - -git checkout master -git branch textual -# spend most of the effort here -git push yourgit textual:textual - -5. Do not worry if you used a stupid-and-wrong branch name, it can be fixed -before submission: - -git branch -m stupid-and-wrong brilliant -git push yourgit brilliant:brilliant :stupid-and-wrong - - -Stay up to date ---------------- - -1. Ensure you have the latest from all remote repositories. - -2. Merge upstream 'master' branch if needed to your local 'master'. - -3. Rebase your working contribution branches. - -4. Push the changes to 'yourgit': - -git fetch --all -git log --graph --decorate --pretty=oneline --abbrev-commit --all - -5. If you notice upstream has changed while you were busy with your -changes rebase on top of the master, but before that: - -6. Push a backup of your branch 'textual' to 'yourgit', then: - -git checkout master -git merge origin/master -git checkout textual -git rebase master - -If rebase reports conflicts, fix the conflicts. If the rebase conflict is -difficult to fix, rebase --abort is a good option, or recover from -'yourgit'; either way, there is some serious re-work ahead with the -change set. - -7. Assuming rebase went fine, push the latest to 'yourgit': - -git push yourgit master:master -git push yourgit --force textual:textual - -The contributor branch tends to need --force every now and then; don't be -afraid to use it. - -8. Push error with master branch - -If 'master' needs --force, something is really messed up. In that -case it is probably wise to abandon(*) local clone, and start all -over from cloning upstream again. Once the upstream is cloned, add -'yourgit' remote again and push: - -git push --mirror yourgit - -But be WARNED: The --mirror will nuke all of your stuff in 'yourgit'; that can -cause data loss. (*)So don't remove the local clone, just move the directory -to the broken repository area. - - -Sending the pull request ------------------------- - -1. When you are happy with your changes, sleep over night. This is not a -speed competition, and for some reason looking at the changes the next day -often makes one realize how things could be improved. This way, you avoid -changing the changes (that is always confusing). - -2. Check the next day that the changes compile without errors or warnings, -and that regression tests run fine: - -make clean && -make -j3 && -make check - -Note that regression tests will not cover all possible cases, so you most -likely need to use the commands, features, and fixes you did manually. - -3. If you need to change something: - -git rebase -i master -# change something -git push -f yourgit textual:textual - -4. You have two ways to send your pull request: - -4.1 Github pull request (recommended) - -This is the recommended way for changes. All you need is to press the -"Pull request" button on GitHub. - -4.2. Send your work to the mailing list (optional) - -Assuming the changes look good, send them to the mailing list. Yes, all -of them! Sending a pull request with GitHub is not visible to project -contributors, and they will not have a chance to review your changes. - -Sending only the pull request, i.e., not each patch, to the mailing list -is also bad. Nothing is as good as seeing the changes as they are, and -being able to find them from with your favorite web search engine from -the mailing list archive. Obviously, the pull request content does not get -indexed, and that is why it is worse. - -git format-patch --cover-letter master..textual -git request-pull upstream/master https://github.com/yourlogin/util-linux.git textual > tempfile - -Take from the 'tempfile' the header: - ----------------------------------------------------------------- -The following changes since commit 17bf9c1c39b4f35163ec5c443b8bbd5857386ddd: - - ipcrm: fix usage (2015-01-06 11:55:21 +0100) - -are available in the git repository at: - - https://github.com/yourlogin/util-linux.git textual ----------------------------------------------------------------- - -Copy and paste it to a 0000-cover-letter.patch file somewhere near 'BLURB -HERE'. The rest of the 'request-pull' output should be ignored. - -In the same file, fix the Subject: line to have reasonable description, for -example: - -Subject: [PATCH 00/15] pull: various textual improvements - - -Feedback and resubmissions --------------------------- - -1. If you sent each patch to the mailing list, you can see which ones got -responses. If the feedback results in changes to the submission then rebase, -perform the changes, and push again to your remote: - -# you probably should use 'Stay up to date' instructions now -git checkout textual -git rebase master -i -# edit something -git add files -git commit --amend -# Add 'Reviewed-by:', 'Tested-by:', 'Signed-off-by:', 'Reference:', and -# other lines near signoff when needed. Attributing the reviewers is a -# virtue, try to do it. -git rebase --continue -git push -f yourgit textual:textual - -2. Send a message to the mailing list that the submitted change has changed, and -that the new version can be found from: - -https://github.com/yourlogin/util-linux/commit/0123456789abcdef0123456789abcdef01234567 - -3. There is no need to update the pull request cover letter. The project -maintainer has done enough of this stuff to know what to do. - - -Repository maintenance ----------------------- - -1. When your remote branch is merged, or you get a final rejection, it is time -to clean it up: - -git branch textual -d -git push yourgit :textual - -2. If you have other contributor repositories configured, you may also -want to clean up the branches the others are done with: - -for I in $(git remote); do - echo "pruning: $I" - git remote prune $I -done - -3. When all of your contributions are processed, you should tidy up the -git's guts: - -git reflog expire --all -git gc --aggressive --prune=now - -Warning: Tidying is not a good idea while you are actively working -with the change set. You never know when you'll need to recover something -from the reflog, so keep that option available until you know the reflog is -not needed. - - -More branches, on top of branches, on top of ... ------------------------------------------------- - -Here is one way of laying out multiple branches: - -git log --graph --decorate --pretty=oneline --abbrev-commit --all -* 13bfff3 (HEAD, docs-update) docs: small improvements to howto-contribute.txt -* 5435d28 (sami/more, more) more: do not call fileno() for std{in,out,err} streams -* 3e1ac04 more: remove unnecessary braces -* c19f31c more: check open(3) return value -* 651ec1b more: move skipping forewards to a function from command() -* bf0c2a7 more: move skipping backwards to a function from command() -* 53a438d more: move editor execution to a function from command() -* b11628b more: move runtime usage output away from command() -* 6cab04e more: avoid long else segment in prbuf() -* a2d9fbb more: remove 'register' keywords -* c6b2d29 more: remove pointless functions -* b41fe34 more: remove function like preprocessor defines -* 1aaa1ce more: use paths.h to find bourne shell and vi editor -* 016a019 more: return is statement, not a function -* ff7019a more: remove dead code and useless comments -* 1705c76 more: add struct more_control and remove global variables -* 3ad4868 more: reorder includes, declarations, and global variables -* 7220e9d more: remove function declarations - BRANCH STATUS: WORK IN PROGRESS -* 04b9544 (sami/script) script: add noreturn function attributes -* e7b8d50 script: use gettime_monotonic() to get timing file timestamps -* 11289d2 script: use correct input type, move comment, and so on -* 524e3e7 script: replace strftime() workaround with CFLAGS = -Wno-format-y2k -* 0465e7f script: move do_io() content to small functions -* 751edca script: add 'Script started' line always to capture file -* f831657 script: remove io vs signal race -* eefc1b7 script: merge doinput() and output() functions to do_io() -* 9eba044 script: use poll() rather than select() -* a6f04ef script: use signalfd() to catch signals -* 4a86d9c script: add struct script_control and remove global variables -* d1cf19c script: remove function prototypes -* 6a7dce9 (sami/2015wk00) fsck.minix: fix segmentation fault -* 5e3bcf7 lslocks: fix type warning -* 3904423 maint: fix shadow declarations -* 17bf9c1 (upstream/master, sami/master, kzgh/master, master) ipcrm: fix usage -[...] - -The above gives a hint to maintainers what the preferred merge order is. -The branches '2015wk00' and 'script' are ready to be merged, and they -were sent to the mailing list. - -The 'more' branch was not submitted at the time of writing this text. -Marking that the branch is not ready is clearly done in the commit subject; -that will need some rebasing before submission. - -A good order for the branches is: - -1. First the minor and safe changes. -2. Then the ready but less certain stuff. -3. Followed by work-in-progress. - -If you go down this route, you will get used to typing a lot of: - -git rebase previous-branch -git push -f yourgit branch:branch - -Alternatively, rebase each branch on top of origin/master, but this is not -quite as good. How can you ensure your own changes are not in conflict -with each other? And there is no hint of the preferred merging order. diff --git a/Documentation/howto-tests.txt b/Documentation/howto-tests.txt deleted file mode 100644 index 15d088089d..0000000000 --- a/Documentation/howto-tests.txt +++ /dev/null @@ -1,152 +0,0 @@ - - util-linux regression tests - ~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - It's expected that for each invasive change or important bugfix you will - include a test to your patch. - - Compile binaries, libs, extra test programs and run the basic tests: - - $ make check - - Compile extra test programs only: - - $ make check-programs - - Note that the configure option --disable-static disables many of libmount and - libblkid unit tests. - - Run all tests including tests that require root permissions: - - # cd tests - # ./run.sh [options, see --help] - - Alternatively using sudo and make: - - $ make check-programs - $ sudo -E make check TS_OPTS="--parallel=1" - - note that as root you have to manually remove output and diff directories - - # rm -rf output diff - - or run 'make clean' as root. - - - Run subset of tests: - - $ cd tests - $ ./run.sh - - for example: - - $ ./run.sh blkid - $ ./run.sh libmount - - or individual test script, for example: - - $ ./ts/cal/year - - The tests is possible to exclude by ./run.sh --exclude= where the - is blank separated test names in format "testdir/testname", for example: - - $ ./run.sh --exclude="mount/move" - - The --exclude is evaluated by the ./run.sh script only. See below - - TS_OPT_testdir_[testscript_]fake= - - environment variable which provides more powerful functionality to skip tests. - - - *** WARNING for root users *** - - The tests touch your /etc/fstab, initialize loop devices or scsi_debug devices - if executed with root permissions. - - Please, be careful and use these tests only for development and never on - production system. - -fuzz targets ------------- - -The fuzz targets can be built and run along with the other tests (after installing -clang): - - $ ./tools/config-gen fuzz - $ make check - -environment variables ---------------------- - -TS_COMMAND - - Evaluated by "make check" to override the default command (run.sh). - Example: - - build all test dependencies, but skip the actual test - $ make check TS_COMMAND="true" - -TS_OPTS - - Evaluated by "make check" to pass options.to run.sh (see ./run.sh --help). - Examples: - - run utmp tests only - $ make check TS_OPTS="--parallel=1 utmp" - -TS_OPT_testdir_[testscript_]fake="" - - Evaluated by any test script to skip certain tests. - Examples: - - skip all the tests within "fdisk" test-directory: - $ make check TS_OPT_fdisk_fake="yes" - - - skip only "fdisk/bsd" test: - $ make check TS_OPT_fdisk_bsd_fake="yes" - - - skip all "fdisk" tests except fdisk/bsd: - $ make check TS_OPT_fdisk_fake="yes" TS_OPT_fdisk_bsd_fake="no" - -TS_OPT_testdir_[testscript_]known_fail="" - - Similar usage like TS_OPT_*_fake above. "known_fail" means that the given - test will run but (negative) results will be ignored. The build log and test - diffs will still remind you about the issue. - -TS_OPT_testdir_[testscript_]verbose="" - - Set verbosity for certain tests. Similar usage like TS_OPT_*_fake above. - -TS_OPT_testdir_[testscript_]memcheck="" - - Run certain tests with valgrind. Similar usage like TS_OPT_*_fake above. - - -External services ------------------ - -Coveralls coverage reports - - URL: https://coveralls.io/github/util-linux/util-linux - -lgtm CI - automatically executed security code analysis - - URL: https://lgtm.com/projects/g/util-linux/util-linux/ - -Coverity Scan - - URL: https://scan.coverity.com/projects/karelzak-util-linux - -Fossies codespell report - - URL: https://fossies.org/linux/test/util-linux-master.tar.gz/codespell.html - -OSS-Fuzz - - URL: https://google.github.io/oss-fuzz/ - URL: https://oss-fuzz-build-logs.storage.googleapis.com/index.html#util-linux - URL: https://oss-fuzz.com/coverage-report/job/libfuzzer_asan_util-linux/latest - -CIFuzz - - URL: https://google.github.io/oss-fuzz/getting-started/continuous-integration/ - URL: https://github.com/util-linux/util-linux/actions?query=workflow%3ACIFuzz diff --git a/Documentation/howto-usage-function.txt b/Documentation/howto-usage-function.txt deleted file mode 100644 index c108bfc89f..0000000000 --- a/Documentation/howto-usage-function.txt +++ /dev/null @@ -1,134 +0,0 @@ - -Example file ------------- - -Refer to the ./boilerplate.c example file while reading this howto. - - -How a usage text is supposed to look ------------------------------------- - -The usage() output format is: Usage section, command description one-liner, -Options section (see below), special sections like 'Available columns', and -the last line is either the man page reference or an empty line. The output -begins with, and each of the above are separated by, one empty line. - -The Usage section contains the synopsis line that describes how to compose -the command. Sometimes you may need multiple synopsis lines (see below). - -Only the synopsis and option lines are indented. Indent is one space (0x40). -Option lines do not use line-ending punctuation. Other sentences do. - -Notations: diamond brackets are used to mark an argument to be filled in; -square brackets are used to mark anything that is optional, such as optional -command arguments, or optional option arguments. In the later case the '=' -character is required in between the option and argument with no whitespace; -three consecutive dots means the unlimited repetition of the preceding. - -The short option is always written first, followed by the long option. They -are separated with a comma and one space. Lonely short or long options do -not affect their alignment. That is, they must be in their respective column. - -Below, in between the snips, is an example of what the usage output should -look like. - --- snip - -Usage: - program [options] [...] - -Short program description, ideally one line only. - -Options: - -n, --no-argument option does not use argument - --optional[=] option argument is optional - -r, --required option requires an argument - -z no long option - --xyzzy a long option only - -e, --extremely-long-long-option - use next line for description when needed - -l, --long-explanation an example of very verbose, and chatty option - description on two, or multiple lines, where the - continuation lines are indented by two spaces - -f, --foobar next option description resets indent - - -h, --help display this help and exit - -V, --version output version information and exit - -For more details see program(1). --- snip - - -Option descriptions -------------------- - -This information also applies to other option-like arguments. That is, -arguments starting with '-'. Such as: functions, commands, and so forth. - -An option description should not exceed the width of 80 characters. If -you need a longer description, use multiple lines and indentation. - -The description text begins from the point of the longest option plus two -spaces. If adding a new option would necessitate a re-indentation of the -descriptions, it either has to be done, or the new option should begin its -description on the next line. Usually the later is better. - -An argument is preferably worded appropriately. For example, if an option -expects a number as argument, '' is a suitable argument indicator. - -The order of the options has no special meaning, with the exception of ---help and --version which are expected to be last ones in the list. - - -Usage function --------------- - -The usage() function will never return. It must only be called by -h/--help. -All other cases use errtryhelp(EXIT_FAILURE). - -Section headers, man page, version, help, and other components of usage() -have string constants defined in 'include/c.h' which must be used. See the -example file listed at the top of this document. The help and version options -are combined into a single macro which takes an argument for the column that -their descriptions will begin on: USAGE_HELP_OPTIONS(). This allows -them to align properly with the other options. - -In the code, all option strings must start at the same position. -See here what this means: - - printf(out, _(" -x[=] default foo is %s"), x); - puts( _(" -y some text"), out); - -Be nice to translators. One gettext entry should be one option, no more, -no less. For example: - - puts(_(" --you-there be nice\n"), out); - puts(_(" -2 translators\n"), out); - puts(_(" -t, --hey are doing a job that we probably cannot," - " or how is your klingon?\n"), out); - -When existing usage output is changed, and it happens to be one big text, -split it into chunks the size of one option. The extra work this will entail -for translators will pay off later; the next string change will not force a -search of the long fuzzy text for what was changed, where, how, and whether -it was the only change. - - -Synopsis --------- - -You may need to use multiple synopsis lines to show that a command does -fundamentally different things depending on the options and/or arguments. -For example, ionice either changes the priority of a running command, or -executes a program with a defined priority. Therefore it is reasonable -to have two synopsis lines: - - ionice [options] -p ... - ionice [options] [ ...] - -Note that the synopsis is not meant to be a repetition of the options -section. The fundamental difference in execution is a bit difficult to -define. The command author, package maintainer or patch submitter will -usually know when it should be done that way. - -