summaryrefslogtreecommitdiffstats
path: root/INSTALL
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--INSTALL190
1 files changed, 190 insertions, 0 deletions
diff --git a/INSTALL b/INSTALL
new file mode 100644
index 0000000..d12fd7a
--- /dev/null
+++ b/INSTALL
@@ -0,0 +1,190 @@
+Name
+ Install - instructions for installing the pages into the system
+
+Synopsis
+ sudo make [-j] install [V=1] [prefix=ARG] [DESTDIR=ARG] [...]
+
+Description
+ (a) Use a package manager
+ If you want to install the manual pages into your system,
+ consider installing them through your package manager from an
+ official release, instead of installing them from this
+ repository. This repository contains the newest manual pages,
+ but using an official release and the system package manager
+ offers important benefits. On a Debian system it would be:
+
+ $ sudo apt-get install -V manpages-dev manpages
+
+ If you prefer to install the manual pages from this repository,
+ maybe because your system ships a too old version, consider
+ updating the package offered by your system. See the <RELEASE>
+ file, and also talk to the maintainer of the package in your
+ distribution.
+
+ (b) Install manually from source
+ If you are contributing to the project, you may want to install
+ the manual pages from this repository to test them, instead of
+ using an official release. Or maybe your distribution installs
+ packages from source code without any package manager.
+
+ In most cases, you just want to install all of the manual pages,
+ and nothing else. To install them in the default system
+ directory (per GNU guidelines), use:
+
+ $ sudo make install
+
+ It takes a few seconds, so it's fine to do it in parallel with:
+
+ $ sudo make -j install
+
+ A few features can be used to tweak the install:
+
+ Variables
+ There are many variables available with which you can tweak
+ the build system. Most of them are directory variables and
+ command variables, based on the GNU Coding Standards. Others
+ are specially designed for this project. To see all of the
+ available variables, use:
+
+ $ make help-variables
+
+ The most common ones that you may use are:
+
+ - DESTDIR
+ - prefix
+
+ Use V=1 for a more verbose output from the makefiles:
+
+ $ sudo make install V=1
+
+ Uninstall
+ You can uninstall the pages with the following command (but
+ see the "Caveats" section below):
+
+ $ sudo make uninstall
+
+ Targets
+ There are targets for more granular control, such as
+ 'install-man3'. See the help to know all of them:
+
+ $ make help
+
+ Dependencies
+ - Build-depends:
+ - Generic:
+ - echo(1)
+ - expr(1)
+ - find(1)
+ - grep(1)
+ - locale(1)
+ - make(1) - GNU Make is required.
+ - sed(1)
+ - sort(1)
+ - xargs(1)
+
+ - For installing:
+ - gzip(1)
+ - install(1)
+ - ln(1)
+ - sponge(1)
+ - test(1)
+
+ - For uninstalling / cleaning:
+ - rm(1)
+ - rmdir(1)
+
+ - For linting/building/checking man(7) source:
+ - eqn(1)
+ - grotty(1)
+ - head(1)
+ - mkdir(1)
+ - tail(1)
+ - tbl(1)
+ - troff(1) >= 1.23.0 - GNU troff is required.
+
+ - For linting/building C source:
+ - cc(1) - GCC or Clang
+ - clang-tidy(1)
+ - cpplint(1)
+ - iwyu(1)
+ - mandoc(1)
+ - mkdir(1)
+ - pkg-config(1)
+ - tac(1)
+ - libbsd-dev
+
+ And one that isn't packaged, but can be extracted from the
+ Linux kernel source tree in <scripts/checkpatch.pl>:
+
+ - checkpatch(1)
+
+ - For building HTML pages:
+ - man2html(1)
+
+ - Depends:
+ - man(1)
+ - groff(1) | mandoc(1)
+
+ Lint & check
+ You can lint and check both the manual pages, and the example C
+ programs contained in them. See 'make help' for a list of
+ targets that can be used.
+
+Files
+ Makefile, share/mk/install-man.mk, share/mk/install.mk
+ Main makefiles for installing (however, others may also be used
+ by inclusion).
+
+ share/mk/cmd.mk
+ Command variables.
+
+ share/mk/install-html.mk
+ Makefile to install HTML manual pages.
+
+ share/mk/verbose.mk
+ Handle verbose settings.
+
+ share/mk/*
+ Other makefiles.
+
+ man*/*
+ Manual pages.
+
+ /usr/local/share/man/man*/*
+ Default location for installed pages.
+
+Standards
+ We follow closely the GNU Coding Standards:
+ <https://www.gnu.org/prep/standards/html_node/Directory-Variables.html>.
+ <https://www.gnu.org/prep/standards/html_node/Command-Variables.html>.
+
+ And the Filesystem Hierarchy Standard:
+ <https://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html>
+
+ But deviate from them in some cases, the most notable case being
+ the use of directories for manual subsections, such as
+ <man3type/>.
+
+Caveats
+ Uninstall
+ You can uninstall the pages. However, take into account that it
+ will only uninstall pages that exist in the repository. This
+ means that if you installed the manual pages from source from an
+ older version of the repository with 'make install', and some
+ page was [re]moved later, it won't be uninstalled. You should
+ probably install with a prefix of prefix=/opt/local/man-pages to
+ be able to nuke the directory later with
+ 'rm -r /opt/local/man-pages'. However, you'll need to modify
+ your $MANPATH to be able to use those manual pages as if they
+ were in a system path.
+
+ Version and last-modified date
+ If you're an end user or a distributor, make sure you do this
+ (install) from a tarball, and not from the git repository. The
+ manual pages in the repository have placeholders for the version
+ and last modified date, which are filled when creating the
+ tarball. You can create your own tarball, for which you need to
+ read the RELEASE file.
+
+See also
+ gmake(1)