[BACK]Return to INSTALL CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/INSTALL, Revision 1.1

1.1     ! schwarze    1: $Id$
        !             2:
        !             3: Installing mdocml, the portable mandoc distribution
        !             4: ---------------------------------------------------
        !             5:
        !             6: The mandoc manpage compiler toolset is a suite of tools compiling
        !             7: mdoc(7), the roff(7) macro language of choice for BSD manual pages,
        !             8: and man(7), the predominant historical language for UNIX manuals.
        !             9: For general information, see:  http://mdocml.bsd.lv/
        !            10:
        !            11: Before manually installing mandoc on your system, please check
        !            12: whether the newest version of mandoc is already installed by default
        !            13: or available via a binary package or a ports system.  A list of the
        !            14: latest bundled and ported versions of mandoc for various operating
        !            15: systems is maintained at:  http://mdocml.bsd.lv/ports.html
        !            16:
        !            17: If mandoc is installed, you can check the version by typing:  mandoc -V
        !            18: The version contained in this distribution tarball is listed near
        !            19: the beginning of the file "Makefile".  Regarding how packages and
        !            20: ports are maintained for your operating system, please consult your
        !            21: operating system documentation.
        !            22:
        !            23:
        !            24: To install mandoc manually, the following steps are needed:
        !            25:
        !            26: 1. Decide whether you want to build just the basic tools mandoc(1),
        !            27: preconv(1) and demandoc(1) or whether you also want to build the
        !            28: database tools apropos(1) and makewhatis(8).  For the latter, a
        !            29: working installation of SQLite is required, see: http://sqlite.org/
        !            30: The recommended version of SQLite is 3.8.4.3 or newer.  The mandoc
        !            31: toolset is known to work with version 3.7.5 or newer.  Versions
        !            32: older than 3.8.3 may not achieve full performance due to the
        !            33: missing SQLITE_DETERMINISTIC optimization flag.  Versions older
        !            34: than 3.8.0 may not show full error information if opening a database
        !            35: fails due to the missing sqlite3_errstr() API.  Both are very minor
        !            36: problems, apropos(1) is fully usable with SQLite 3.7.5.
        !            37: The database tools also require Marc Espie's ohash(3) library;
        !            38: if your system does not have it, the bundled compatibility version
        !            39: will be used, so you probably need not worry about it.
        !            40:
        !            41: 2. If you choose to build the database tools, too, decide whether
        !            42: you also want to build the CGI program, man.cgi(8).
        !            43:
        !            44: 3. Read the beginning of the file "Makefile" from "USER SETTINGS"
        !            45: to "END OF USER SETTINGS" and edit it as required.  In particular,
        !            46: disable "BUILD_TARGETS += db-build" if you do not want database
        !            47: support or enable "BUILD_TARGETS += cgi-build" if you do want
        !            48: the CGI program.
        !            49:
        !            50: 4. Run the command "make".  No separate "./configure" or "make
        !            51: depend" steps are needed.  The former is run automatically by "make".
        !            52: The latter is a maintainer target.  If you merely want to build the
        !            53: released version as opposed to doing active development, there is
        !            54: no need to regenerate the dependency specifications.  Any
        !            55: POSIX-compatible make, in particular both BSD make and GNU make,
        !            56: is supposed to work.
        !            57:
        !            58: 5. Run the command "make -n install" and check whether everything
        !            59: will be installed to the intended places.  Otherwise, edit the *DIR
        !            60: variables in the Makefile until it is.
        !            61:
        !            62: 6. Run "sudo make install".  Instead, if you intend to build a binary
        !            63: package using some kind of fake root mechanism, you may need a
        !            64: command like "make DESTDIR=... install".  Read the *-install targets
        !            65: in the "Makefile" to understand how DESTDIR is used.
        !            66:
        !            67:
        !            68: If you want to check whether automatic configuration works well
        !            69: on your platform, consider the following:
        !            70:
        !            71: The mandoc package intentionally does not use GNU autoconf because
        !            72: we consider that toolset a blatant example of overengineering that
        !            73: is obsolete nowadays, since all modern operating systems are now
        !            74: reasonably close to POSIX and do not need arcane shell magic any
        !            75: longer.  If your system does need such magic, consider upgrading
        !            76: to reasonably modern POSIX-compliant tools rather than asking for
        !            77: autoconf-style workarounds.
        !            78:
        !            79: As far as mandoc is using any features not mandated by ANSI X3.159-1989
        !            80: ("ANSI C") or IEEE Std 1003.1-2008 ("POSIX") that some modern systems
        !            81: do not have, we intend to provide autoconfiguration tests and
        !            82: compat_*.c implementations.  Please report any that turn out to be
        !            83: missing.  Note that while we do strive to produce portable code,
        !            84: we do not slavishly restrict ourselves to POSIX-only interfaces.
        !            85: For improved security and readability, we do use well-designed,
        !            86: modern interfaces like reallocarray(3) even if they are still rather
        !            87: uncommon, of course bundling compat_*.c implementations as needed.
        !            88:
        !            89: Where mandoc is using ANSI C or POSIX features that some systems
        !            90: still lack and that compat_*.c implementations can be provided for
        !            91: without too much hassle, we will consider adding them, too, so
        !            92: please report whatever is missing on your platform.
        !            93:
        !            94: The following steps can be used to manually check the automatic
        !            95: configuration on your platform:
        !            96:
        !            97: 1. Run "make clean".
        !            98:
        !            99: 2. Run "make config.h"
        !           100:
        !           101: 3. Read the file "config.log".  It shows the compiler commands used
        !           102: to test the libraries installed on your system and the standard
        !           103: output and standard error output these commands produce.  Watch out
        !           104: for unexpected failures.  Those are most likely to happen if headers
        !           105: or libraries are installed in unusual places or interfaces defined
        !           106: in unusual headers.  You can also look at the file "config.h" and
        !           107: check that no expected "#define HAVE_*" lines are missing.  The
        !           108: list of tests run can be found in the file "configure".
        !           109:
        !           110:
        !           111: In case you have questions or want to provide feedback, look at:
        !           112: http://mdocml.bsd.lv/contact.html
        !           113:
        !           114: Consider subscribing to the discuss@ mailing list mentioned on that
        !           115: page.  If you intend to help with the development of mandoc, consider
        !           116: subscribing to the tech@ mailing list, too.
        !           117:
        !           118: Enjoy using the mandoc toolset!
        !           119: Ingo Schwarze, Karlsruhe, August 2014

CVSweb