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           -  Generic:
  71              -  echo(1)
  72              -  expr(1)
  73              -  find(1)
  74              -  grep(1)
  75              -  locale(1)
  76              -  make(1) - GNU Make is required.
  77              -  sed(1)
  78              -  sort(1)
  79              -  xargs(1)
  80
  81           -  For installing:
  82              -  gzip(1)
  83              -  install(1)
  84              -  ln(1)
  85              -  sponge(1)
  86              -  test(1)
  87
  88           -  For uninstalling / cleaning:
  89              -  rm(1)
  90              -  rmdir(1)
  91
  92           -  For linting/building/checking man(7) source:
  93              -  eqn(1)
  94              -  grotty(1)
  95              -  head(1)
  96              -  mkdir(1)
  97              -  tail(1)
  98              -  tbl(1)
  99              -  troff(1) >= 1.23.0 - GNU troff is required.
 100
 101           -  For linting/building C source:
 102              -  cc(1) - GCC or Clang
 103              -  clang-tidy(1)
 104              -  cpplint(1)
 105              -  iwyu(1)
 106              -  mandoc(1)
 107              -  mkdir(1)
 108              -  pkg-config(1)
 109              -  tac(1)
 110              -  libbsd-dev
 111
 112              And one that isn't packaged, but can be extracted from the
 113              Linux kernel source tree in <scripts/checkpatch.pl>:
 114
 115              -  checkpatch(1)
 116
 117           -  For building HTML pages:
 118              -  man2html(1)
 119
 120        -  Depends:
 121           -  man(1)
 122           -  groff(1) | mandoc(1)
 123
 124    Lint & check
 125        You can lint and check both the manual pages, and the example C
 126        programs contained in them.  See 'make help' for a list of
 127        targets that can be used.
 128
 129 Files
 130    GNUmakefile, share/mk/install-man.mk, share/mk/install.mk
 131        Main makefiles for installing (however, others may also be used
 132        by inclusion).
 133
 134    share/mk/cmd.mk
 135        Command variables.
 136
 137    share/mk/install-html.mk
 138        Makefile to install HTML manual pages.
 139
 140    share/mk/verbose.mk
 141        Handle verbose settings.
 142
 143    share/mk/*
 144        Other makefiles.
 145
 146    man*/*
 147        Manual pages.
 148
 149    /usr/local/share/man/man*/*
 150        Default location for installed pages.
 151
 152 Standards
 153        We follow closely the GNU Coding Standards:
 154        <https://www.gnu.org/prep/standards/html_node/Directory-Variables.html>.
 155        <https://www.gnu.org/prep/standards/html_node/Command-Variables.html>.
 156
 157        And the Filesystem Hierarchy Standard:
 158        <https://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html>
 159
 160        But deviate from them in some cases, the most notable case being
 161        the use of directories for manual subsections, such as
 162        <man3type/>.
 163
 164 Caveats
 165    Uninstall
 166        You can uninstall the pages.  However, take into account that it
 167        will only uninstall pages that exist in the repository.  This
 168        means that if you installed the manual pages from source from an
 169        older version of the repository with 'make install', and some
 170        page was [re]moved later, it won't be uninstalled.  You should
 171        probably install with a prefix of prefix=/opt/local/man-pages to
 172        be able to nuke the directory later with
 173        'rm -r /opt/local/man-pages'.  However, you'll need to modify
 174        your $MANPATH to be able to use those manual pages as if they
 175        were in a system path.
 176
 177    Version and last-modified date
 178        If you're an end user or a distributor, make sure you do this
 179        (install) from a tarball, and not from the git repository.  The
 180        manual pages in the repository have placeholders for the version
 181        and last modified date, which are filled when creating the
 182        tarball.  You can create your own tarball, for which you need to
 183        read the RELEASE file.
 184
 185 See also
 186        gmake(1)