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