fixing backslash escaping in tables, refine the compatibility table
[nobug] / doc / buildinstall.txt
1 HEAD- Building and Installing;;
2
3 HEAD++ Supported Platforms;;
4
5 NoBug has been developed on linux, using gcc. It should be possible to port
6 it to any other POSIX compliant operating system. Platform/compiler
7 specific things are kept optional. Currently Linux with a gcc that conforms to
8 C99 is supported for both 32 and 64 bit architectures. For non gcc compilers
9 some features are not available or degraded.
10
11 [frame="topbot",options="header", cols="<,<,<,<,<m"]
12 |=================================================================================
13 |CPU    |OS          |Compiler    |State     |
14 |x86_64 |Debian      |gcc4        |supported |Reference Platform
15 |x86    |other Linux |gcc4        |supported |Please report distro specific problems
16 |armel  |maemo5      |gcc4        |supported |check fails in SDK (emulator bug)
17 |x86*   |Mac OS X    |gcc4        |supported |
18 |x86    |OpenSolaris |gcc4, suncc |mostly    |Builds, but target check fails
19 |       |*BSD        |            |planned   |Need volunteer for testing
20 |=================================================================================
21
22 NoBug has few mandatory dependencies on other software and libraries,
23 some things such as valgrind support are optional and should be automatially
24 detected during the build, i.e., when `./configure` is called. Nevertheless it
25 requires 'pkg-config' to be installed, you get some weird errors already at
26 bootstrapping (autoreconf) when this is not available.
27
28
29 HEAD== Release Tarballs;;
30
31 Releases are available at:
32  http://www.pipapo.org/nobug-releases/[]
33
34 Gpg signed tarballs are being used for distribution. The first step involves
35 checking the signature:
36
37  $ gpg nobug-VERSION.tar.gz.gpg
38
39 This will produce a nobug-VERSION.tar.gz and report if the signature could be
40 validated.
41
42 Since they are built with gnu autotools, the usual build and install procedure
43 will work:
44
45  $ tar xzvf nobug-VERSION.tar.gz
46  $ cd nobug-VERSION
47  $ mkdir -p build
48  $ cd build
49  $ ../configure
50  $ make
51  $ make check           # optional, run the testsuite
52  $ make install         # to be done as root,
53                         # depending on distribution and setup
54
55
56 HEAD== Development Version via git;;
57
58 You can obtain a development version by using git.  The git repository can be
59 cloned from `git://git.pipapo.org/nobug`.
60
61 Clone the git repository by:
62
63  $ git clone git://git.pipapo.org/nobug
64
65 After cloning the repository, then bootstrap the autotools:
66
67  $ cd nobug
68  $ autoreconf -i                # creates the configure file
69
70 Then the usual
71
72  $ cd build && ../configure && make && make install
73
74 (as above) will work. Careful users may run
75
76  $ make check
77
78 to run a testsuite before installing.
79
80
81 HEAD++ Keeping Git Up To Date;;
82
83 To update to any new revision, just enter the nobug dir and
84
85  $ git pull
86
87 After that you can build as above
88
89  $ cd build && ../configure && make && make install
90
91 This default pull will update from the 'master' branch which is meant to be an on-going
92 stable version (latest release and bugfixes).
93
94 HEAD-- What Is Installed;;
95
96 Currently, NoBug installs the following:
97
98   * A single nobug.h headerfile. Include this in your code.
99   * Static libraries. Statically link these to your application:
100     - `libnobug.a` for singlethreaded programs.
101     - `libnobugmt.a` for multithreaded programs.
102   * Dynamic Libraries. Dynamically link these to your application:
103     - `libnobug.so` for singlethreaded programs.
104     - `libnobugmt.so` for multithreaded programs.
105     - associated libtool descriptors (`libnobug*.la`)
106   * Pkgconfig control files:
107     - `nobug.pc` for singlethreaded programs.
108     - `nobugmt.pc` for multithreaded programs.
109   * The `nobug_rbdump` utility to inspect NoBug ringbuffers.
110
111
112 HEAD== Generating This Documentation;;
113
114 There are Makefile targets for generating the documentation, either one of the
115 following does what you might expect:
116
117  $ make nobug_manual.txt nobug_manual.html nobug_manual.pdf
118
119 Alternatively, you can generate all the documentation in one go as follows:
120
121   $ make doc
122
123 Building the documentation has quite some more dependencies than building
124 NoBug itself. Unless you are a packager you may prefer to refer to the online
125 documentation or the shipped 'README' which is the complete nobug reference
126 manual in text form. Generating the documentation requires: gawk, asciidoc,
127 graphviz and some tool chains to further process docbook and latex.
128