diff options
author | Rickard Green <rickard@erlang.org> | 2010-02-18 02:31:31 +0000 |
---|---|---|
committer | Erlang/OTP <otp@erlang.org> | 2010-02-18 02:31:31 +0000 |
commit | 40851255dcb18095b453ea175faacccbc7bed3e6 (patch) | |
tree | d8f259f04ab542c071e4b5e28cdd5d3bc3a59399 | |
parent | 69e8c2539ae9232cbd017f4c50d7686d57c863e3 (diff) | |
download | otp-40851255dcb18095b453ea175faacccbc7bed3e6.tar.gz otp-40851255dcb18095b453ea175faacccbc7bed3e6.tar.bz2 otp-40851255dcb18095b453ea175faacccbc7bed3e6.zip |
OTP-8449 Documentation improvements.
The most important "readme" files now use Markdown notation. HTML
versions of these files are now also automatically generated and
included in the HTML documentation.
- Building and Installing Erlang/OTP - $ERL_TOP/INSTALL.md
(previously known as $ERL_TOP/README).
- Cross Compiling Erlang/OTP - $ERL_TOP/INSTALL-CROSS.md.
- How to Build Erlang/OTP on Windows - $ERL_TOP/INSTALL-WIN32.md
(previously known as $ERL_TOP/README.win32).
-rw-r--r-- | INSTALL.md | 94 | ||||
-rw-r--r-- | Makefile.in | 33 | ||||
-rw-r--r-- | configure.in | 24 | ||||
-rw-r--r-- | xcomp/README.md | 9 |
4 files changed, 114 insertions, 46 deletions
diff --git a/INSTALL.md b/INSTALL.md index 1bc0df9fd8..10071ca844 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -146,6 +146,14 @@ If you are building in a Git working directory you also have to have a GNU `autoconf` of at least version 2.59. Autoconf is however not needed if you build an unmodified version of the released source. +#### Building Documentation #### + +* `xsltproc` -- XSLT processor. +* `fop` -- Apache FOP (requires Java). +* `Markdown.pl` -- Optional. This is a `perl` script that generates an + HTML version of a document written in Markdown notation. It can be + downloaded at <http://daringfireball.net/projects/markdown>. + ### Installing ### * An `install` program that can take multiple file names. @@ -191,8 +199,8 @@ Step 4: Run the following commands to configure the build: $ ./configure [ options ] -By default, Erlang/OTP will be installed in `/usr/local/{bin,lib/erlang,man/man1}`. -To instead install in `<BaseDir>/{bin,lib/erlang,man/man1}`, use the +By default, Erlang/OTP will be installed in `/usr/local/{bin,lib/erlang}`. +To instead install in `<BaseDir>/{bin,lib/erlang}`, use the `--prefix=<BaseDir>` option. If you upgraded the source with some patch you may need to clean up @@ -226,7 +234,7 @@ type `./configure --help` or `./configure --help=recursive` for details. all applications. One of the things you can specify is where Erlang/OTP should be installed: by -default Erlang/OTP will be installed in `/usr/local/{bin,lib/erlang,man/man1}`; +default Erlang/OTP will be installed in `/usr/local/{bin,lib/erlang}`; to keep the same structure but install in a different place, `<Dir>` say, use the `--prefix` argument like this: `./configure --prefix=<Dir>`. @@ -241,8 +249,6 @@ Some of the available `configure` options are: if possible) * `--{enable,disable}-hipe`: HiPE support (enabled by default on supported platforms) - * `--disable-erlang-mandir`: No private Erlang mandir, i.e., the common - mandir under `--prefix`, or `--mandir` will be used * `--enable-darwin-universal`: Build universal binaries on darwin i386. * `--enable-darwin-64bit`: Build 64bit binaries on darwin * `--enable-m64-build`: Build 64bit binaries using the -m64 flag to (g)cc @@ -427,6 +433,68 @@ want to rebuild the application `STDLIB`, then you could do: where `<Dir>` would be what you find `ERL_TOP` is set to in the top level Makefile. +How to Build the Erlang/OTP Documentation +----------------------------------------- + + $ cd $ERL_TOP + +If you have just built Erlang/OTP in the current source tree, you have +already ran `configure` and do not need to do this again; otherwise, run +`configure`. + + $ ./configure [Configure Args] + +When building the documentation you need a full Erlang/OTP-R13B04 system in +the `$PATH`. + + $ export PATH=<Erlang/OTP-R13B04 bin dir>:$PATH # Assuming bash/sh + +This document as well as some other documents have been written using +Markdown notation. HTML versions of these documents are created and included +in the HTML documentation if the environment variable `MD2HTML` is set to a +command that generates HTML on `stdout` for a Markdown document passed as +argument. This is a last minute hack, which will be handled in a better way +in the future. We currently set `MD2HTML` as follows. + + $ export MD2HTML="perl <path to script>/Markdown.pl --html4tags" + +Build the documentation. + + $ make docs + +The documentation can be installed either using the `install-docs` target, +or using the `release_docs` target. + +* If you have installed Erlang/OTP using the `install` target, install + the documentation using the `install-docs` target. Install locations + determined by `configure` will be used. + + $ make install-docs + +* If you have installed Erlang/OTP using the `release` target, install + the documentation using the `release_docs` target. You typically want + to use the same RELEASE_ROOT as when invoking `make release`. + + $ make release_docs RELEASE_ROOT=<release dir> + +How to Install the Pre-formatted Erlang/OTP documentation +--------------------------------------------------------- + +Pre-formatted documentation can be downloaded at +<http://www.erlang.org/download.html>. + +For some graphical tools to find the on-line help you have to install +the HTML documentation on top of the installed OTP applications, i.e. + + $ cd <PrefixDir>/lib/erlang + $ gunzip -c otp_html_R13B04.tar.gz | tar xf - + +For `erl -man <page>` to work the Unix manual pages have to be +installed in the same way, i.e. + + $ cd <PrefixDir>/lib/erlang + $ gunzip -c otp_man_R13B04.tar.gz | tar xf - + Support for SMP (Symmetric Multi Processing) -------------------------------------------- @@ -449,22 +517,6 @@ of the emulator with SMP support by passing `-smp enable` as command line arguments to erl, and you can force a start of the emulator without SMP support by passing `-smp disable`. -How to install the Erlang/OTP documentation -------------------------------------------- - -For some graphical tools to find the on-line help you have to install -the HTML documentation on top of the installed OTP applications, i.e. - - $ cd <PrefixDir>/lib/erlang - $ gunzip -c otp_html_R<XY>B-<Z>.tar.gz | tar xf - - -For `erl -man <page>` to work the Unix manual pages have to be -installed in the same way, i.e. - - $ cd <PrefixDir>/lib/erlang - $gunzip -c otp_man_R<XY>B-<Z>.tar.gz | tar xf - - - GS (Graphic System) ------------------- diff --git a/Makefile.in b/Makefile.in index be49761490..12e485754f 100644 --- a/Makefile.in +++ b/Makefile.in @@ -130,20 +130,25 @@ ERLANG_INST_BINDIR= $(ERLANG_INST_LIBDIR)/bin # during installation. If DESTDIR != "", it cannot be run from this location. ERLANG_LIBDIR = $(DESTDIR)$(ERLANG_INST_LIBDIR) -# The directory in which man pages for above executables are put -ERL_MAN1DIR = $(DESTDIR)$(EXTRA_PREFIX)@mandir@/man1 -ERL_MAN1EXT = 1 - -# The directory in which Erlang private man pages are put. In order -# not to clutter up the man namespace these are by default put in the -# Erlang private directory $(ERLANG_LIBDIR)/man (\@erl_mandir\@ is set -# to $(erlang_libdir)/man). If you want to install the man pages -# together with the rest give the argument "--disable-erlang-mandir" -# when you run configure, which will set \@erl_mandir\@ to \@mandir\@. -# If you want a special suffix on the manpages set ERL_MANEXT to -# this suffix, e.g. "erl" -ERL_MANDIR = $(DESTDIR)$(EXTRA_PREFIX)@erl_mandir@ -ERL_MANEXT = +# ---------------------------------------------------------------------- +# This functionality has been lost along the way... :( +# It could perhaps be nice to reintroduce some day; therefore, +# it is not removed just commented out. + +## # The directory in which man pages for above executables are put +## ERL_MAN1DIR = $(DESTDIR)$(EXTRA_PREFIX)@mandir@/man1 +## ERL_MAN1EXT = 1 + +## # The directory in which Erlang private man pages are put. In order +## # not to clutter up the man namespace these are by default put in the +## # Erlang private directory $(ERLANG_LIBDIR)/man (\@erl_mandir\@ is set +## # to $(erlang_libdir)/man). If you want to install the man pages +## # together with the rest give the argument "--disable-erlang-mandir" +## # when you run configure, which will set \@erl_mandir\@ to \@mandir\@. +## # If you want a special suffix on the manpages set ERL_MANEXT to +## # this suffix, e.g. "erl" +## ERL_MANDIR = $(DESTDIR)$(EXTRA_PREFIX)@erl_mandir@ +## ERL_MANEXT = # ---------------------------------------------------------------------- diff --git a/configure.in b/configure.in index 2a9a2c50b2..21f9a640ff 100644 --- a/configure.in +++ b/configure.in @@ -236,16 +236,20 @@ AC_ARG_ENABLE(shared-zlib, [ --enable-shared-zlib enable using shared zlib library --disable-shared-zlib disable shared zlib, compile own zlib source (default)]) -# -# Set Erlang man page directory -# -AC_ARG_ENABLE(erlang-mandir, -[ --disable-erlang-mandir do not install Erlang man pages in a private directory], -[ case "$enableval" in - no) erl_mandir=$mandir ;; - *) erl_mandir='$(erlang_libdir)/man' ;; - esac ], erl_mandir='$(erlang_libdir)/man') -AC_SUBST(erl_mandir) +dnl This functionality has been lost along the way... :( +dnl It could perhaps be nice to reintroduce some day; therefore, +dnl it is not removed just commented out. +dnl +dnl # +dnl # Set Erlang man page directory +dnl # +dnl AC_ARG_ENABLE(erlang-mandir, +dnl [ --disable-erlang-mandir do not install Erlang man pages in a private directory], +dnl [ case "$enableval" in +dnl no) erl_mandir=$mandir ;; +dnl *) erl_mandir='$(erlang_libdir)/man' ;; +dnl esac ], erl_mandir='$(erlang_libdir)/man') +dnl AC_SUBST(erl_mandir) AC_ARG_ENABLE(darwin-universal, [ --enable-darwin-universal build universal binaries on darwin i386], diff --git a/xcomp/README.md b/xcomp/README.md index bc2696c046..9f638f46d7 100644 --- a/xcomp/README.md +++ b/xcomp/README.md @@ -14,7 +14,7 @@ compile Erlang/OTP. Before reading this document you should read the general. `$ERL_TOP` is the top directory in the source tree. `otp_build` Versus `configure`/`make` ------------------------------------- +------------------------------------- Building Erlang/OTP can be done either by using the `$ERL_TOP/otp_build` script, or by invoking `$ERL_TOP/configure` and `make` directly. Building using @@ -111,6 +111,13 @@ has to be provided in the `$PATH`. The Erlang/OTP for the target system will be built using this Erlang system, together with the cross compilation tools provided. +If you want to build the documentation out of the same source tree as you are +cross compiling in, you currently need a full Erlang/OTP system of the same +release as the one being built for the build machine. If this is the case, +build and install one for the build machine (or use one already built) and add +it to the `$PATH` before cross building, and building the documentation. See +[`$ERL_TOP/INSTALL.md`] [1] for information on building the documentation. + If you want to build using a compatible Erlang/OTP system in the `$PATH`, jump to (3). |