INSTALL

   1 Name
   2        Install - instructions for installing the pages into the system
   3
   4 Synopsis
   5        sudo make [-j] install [prefix=ARG] [DESTDIR=ARG] [...]
   6
   7 Description
   8    (a)  Use a package manager
   9        If you want to install the manual pages into your system,
  10        consider installing them through your package manager from an
  11        official release, instead of installing them from this
  12        repository.  This repository contains the newest manual pages,
  13        but using an official release and the system package manager
  14        offers important benefits.  On a Debian system it would be:
  15
  16            $ sudo apt-get install -V manpages-dev manpages
  17
  18        If you prefer to install the manual pages from this repository,
  19        maybe because your system ships a too old version, consider
  20        updating the package offered by your system.  See the <RELEASE>
  21        file, and also talk to the maintainer of the package in your
  22        distribution.
  23
  24    (b)  Install manually from source
  25        If you are contributing to the project, you may want to install
  26        the manual pages from this repository to test them, instead of
  27        using an official release.  Or maybe your distribution installs
  28        packages from source code without any package manager.
  29
  30        In most cases, you just want to install all of the manual pages,
  31        and nothing else.  To install them in the default system
  32        directory (per GNU guidelines), use:
  33
  34            $ sudo make install
  35
  36        It takes a few seconds, so it's fine to do it in parallel with:
  37
  38            $ sudo make -j install
  39
  40        A few features can be used to tweak the install:
  41
  42        Variables
  43            There are many variables available with which you can tweak
  44            the build system.  Most of them are directory variables and
  45            command variables, based on the GNU Coding Standards.  Others
  46            are specially designed for this project.  To see all of the
  47            available variables, use:
  48
  49                $ make help
  50
  51            The most common ones that you may use are:
  52
  53            -  DESTDIR
  54            -  prefix
  55
  56        Uninstall
  57            You can uninstall the pages with the following command (but
  58            see the "Caveats" section below):
  59
  60                $ sudo make uninstall
  61
  62        Targets
  63            There are targets for more granular control, such as
  64            'install-man3'.  See the help to know all of them:
  65
  66                $ make help
  67
  68    Dependencies
  69        To see the build-dependencies of the project, that is, the
  70        dependencies of the build system, see `make help`.
  71
  72        To read the manual pages, you'll need:
  73
  74        -  man(1)
  75        -  groff(1) | mandoc(1)
  76
  77    Lint & check
  78        You can lint and check both the manual pages, and the example C
  79        programs contained in them.  See 'make help' for a list of
  80        targets that can be used.
  81
  82 Files
  83    GNUmakefile, share/mk/install-man.mk, share/mk/install.mk
  84        Main makefiles for installing (however, others may also be used
  85        by inclusion).
  86
  87    share/mk/cmd.mk
  88        Command variables.
  89
  90    share/mk/install-html.mk
  91        Makefile to install HTML manual pages.
  92
  93    share/mk/verbose.mk
  94        Handle verbose settings.
  95
  96    share/mk/*
  97        Other makefiles.
  98
  99    man*/*
 100        Manual pages.
 101
 102    /usr/local/share/man/man*/*
 103        Default location for installed pages.
 104
 105 Standards
 106        We follow closely the GNU Coding Standards:
 107        <https://www.gnu.org/prep/standards/html_node/Directory-Variables.html>.
 108        <https://www.gnu.org/prep/standards/html_node/Command-Variables.html>.
 109
 110        And the Filesystem Hierarchy Standard:
 111        <https://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html>
 112
 113        But deviate from them in some cases, the most notable case being
 114        the use of directories for manual subsections, such as
 115        <man3type/>.
 116
 117 Caveats
 118    Uninstall
 119        You can uninstall the pages.  However, take into account that it
 120        will only uninstall pages that exist in the repository.  This
 121        means that if you installed the manual pages from source from an
 122        older version of the repository with 'make install', and some
 123        page was [re]moved later, it won't be uninstalled.  You should
 124        probably install with a prefix of prefix=/opt/local/man-pages to
 125        be able to nuke the directory later with
 126        'rm -r /opt/local/man-pages'.  However, you'll need to modify
 127        your $MANPATH to be able to use those manual pages as if they
 128        were in a system path.
 129
 130    Version and last-modified date
 131        If you're an end user or a distributor, make sure you do this
 132        (install) from a tarball, and not from the git repository.  The
 133        manual pages in the repository have placeholders for the version
 134        and last modified date, which are filled when creating the
 135        tarball.  You can create your own tarball, for which you need to
 136        read the RELEASE file.
 137
 138 See also
 139        gmake(1)