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-variables
  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        -  Build-depends:
  70
  71           To learn the build dependencies of the project, run
  72
  73               $ find share/mk/ -type f \
  74               | xargs grep include.*configure/build-depends/ \
  75               | sed 's,share/mk/,,' \
  76               | sed 's,/.*:,:,' \
  77               | sed 's,include $.*/, ,' \
  78               | sed 's,\.mk,,g' \
  79               | sort \
  80               | uniq;
  81
  82        -  Depends:
  83           -  man(1)
  84           -  groff(1) | mandoc(1)
  85
  86    Lint & check
  87        You can lint and check both the manual pages, and the example C
  88        programs contained in them.  See 'make help' for a list of
  89        targets that can be used.
  90
  91 Files
  92    GNUmakefile, share/mk/install-man.mk, share/mk/install.mk
  93        Main makefiles for installing (however, others may also be used
  94        by inclusion).
  95
  96    share/mk/cmd.mk
  97        Command variables.
  98
  99    share/mk/install-html.mk
 100        Makefile to install HTML manual pages.
 101
 102    share/mk/verbose.mk
 103        Handle verbose settings.
 104
 105    share/mk/*
 106        Other makefiles.
 107
 108    man*/*
 109        Manual pages.
 110
 111    /usr/local/share/man/man*/*
 112        Default location for installed pages.
 113
 114 Standards
 115        We follow closely the GNU Coding Standards:
 116        <https://www.gnu.org/prep/standards/html_node/Directory-Variables.html>.
 117        <https://www.gnu.org/prep/standards/html_node/Command-Variables.html>.
 118
 119        And the Filesystem Hierarchy Standard:
 120        <https://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html>
 121
 122        But deviate from them in some cases, the most notable case being
 123        the use of directories for manual subsections, such as
 124        <man3type/>.
 125
 126 Caveats
 127    Uninstall
 128        You can uninstall the pages.  However, take into account that it
 129        will only uninstall pages that exist in the repository.  This
 130        means that if you installed the manual pages from source from an
 131        older version of the repository with 'make install', and some
 132        page was [re]moved later, it won't be uninstalled.  You should
 133        probably install with a prefix of prefix=/opt/local/man-pages to
 134        be able to nuke the directory later with
 135        'rm -r /opt/local/man-pages'.  However, you'll need to modify
 136        your $MANPATH to be able to use those manual pages as if they
 137        were in a system path.
 138
 139    Version and last-modified date
 140        If you're an end user or a distributor, make sure you do this
 141        (install) from a tarball, and not from the git repository.  The
 142        manual pages in the repository have placeholders for the version
 143        and last modified date, which are filled when creating the
 144        tarball.  You can create your own tarball, for which you need to
 145        read the RELEASE file.
 146
 147 See also
 148        gmake(1)