Merge pull request #36 from jamesodhunt/improve-docs

Improve docs

README-BUILD.md

@@ -1,14 +1,70 @@
-# Building on FreeBSD
+# Build procenv
+
+## Build from source
+
+1. Install dependencies
+
+   | Platform | Usage | Required? | Dependency | Rationale |
+   |-|-|-|-|-|
+   | common | build | yes | GCC or Clang compiler | For building the code |
+   | common | build | yes | GNU Autoconf | For configuring the source package |
+   | common | build | yes | GNU Autoconf Archive | For configuring the source package |
+   | common | build | yes | GNU Automake | For generating makefiles |
+   | common | build | yes | GNU Make | For building the code |
+   | common | build | yes | `pkgconf` / `pkg-config` | For configuring build dependencies |
+   | common | test | optional | Check | For running unit tests |
+   | common | test | optional | Expat | For validating XML output |
+   | common | test | optional | GNU Groff | For checking man page documentation |
+   | Linux | build | optional | `libapparmor` development package | For AppArmor details |
+   | Linux | build | optional | `libcap` development package | For capabilities details |
+   | Linux | build | optional | `libnuma` development package | For NUMA memory details |
+   | Linux | build | optional | `libselinux` development package | For SELinux details |
+   | BSD | build | optional | `libsysinfo` package or port | For general memory details |
+
+   > **Note:**
+   >
+   > The definitive list of dependenciese can always be seen by looking at the GitHub Actions workflow file here:
+   >
+   > - [`.github/workflows/build.yaml`](.github/workflows/build.yaml)
+
+1. Checkout the source code:
+
+   ```bash
+   $ git clone https://github.com/jamesodhunt/procenv
+   $ cd procenv
+   ```
+
+1. Configure and build:
+
+   ```bash
+   $ autoreconf -fi && ./configure
+   $ make && make check && sudo make install
+   ```
+
+   > **Note:**
+   >
+   > For BSD systems, replace `make` with `gmake` above to ensure you run using
+   > GNU Make (BSD make will hang at the test stage!)
+
+## Build snap package
+
+```bash
+$ git clone https://github.com/jamesodhunt/procenv
+$ cd procenv
+$ snapcraft
+```
+
+### Build on FreeBSD
 
 FreeBSD is awkward. This worked for me on FreeBSD 10.2:
 
 ```bash
 $ gmake CC=clang-devel LD=ld.gold LDFLAGS='-v -fuse-ld=gold'
 ```
 
-# Building on Minix
+### Build on Minix
 
-Try this::
+Try this:
 
 ```bash
 $ ./configure CC=clang CFLAGS='-I/usr/pkg/include' LDFLAGS='-L/usr/pkg/lib'

README-DEVELOPER.md

@@ -0,0 +1,18 @@
+# procenv developer details
+
+> **Note:**
+>
+> This document assumes you have already read the
+> [build document](README-BUILD.md).
+
+## Debug with gdb or lldb
+
+To disable optimisations when building `procenv`, configure by specifying
+the `--disable-compiler-optimisations` configure option (which sets the
+`-O0` compiler option):
+
+```bash
+$ /configure --disable-compiler-optimisations
+$ make
+$ gdb src/procenv
+```

README.md

@@ -125,7 +125,7 @@ init=/usr/bin/procenv PROCENV_FILE=/dev/ttyS0 PROCENV_EXEC="/sbin/init --foo-bar
 - GNU Hurd
 - GNU Linux
 - macOS
-- [Minix 3](README-BUILD.md)
+- [Minix 3](#minix)
 
 It unashamedly emulates a number of existing system utilities as it is
 attempting to be all-encompassing: I wrote it with the aim of being able to
@@ -136,6 +136,15 @@ program (by default). Also, the line of demarcation between "process",
 `procenv` shows these too since they are obviously meant to be queryable by
 applications.
 
+## Build
+
+For instructions on building from source, see also the
+[build document](README-BUILD.md).
+
+## Developer documentation
+
+See the [developer document](README-DEVELOPER.md).
+
 ## Install
 
 ### Snap
@@ -188,6 +197,10 @@ $ sudo make install clean
 
 > **Note:** See also the [build document](README-BUILD.md).
 
+### Minix
+
+See also the [build document](README-BUILD.md).
+
 ### Gentoo
 
 ```bash
@@ -208,62 +221,6 @@ $ sudo port install procenv
 $ sudo zypper install -y procenv
 ```
 
-## Build
-
-## Build snap package
-
-```bash
-$ git clone https://github.com/jamesodhunt/procenv
-$ cd procenv
-$ snapcraft
-```
-
-## Build from source
-
-1. Install dependencies
-
-   | Platform | Usage | Required? | Dependency | Rationale |
-   |-|-|-|-|-|
-   | common | build | yes | GCC or Clang compiler | For building the code |
-   | common | build | yes | GNU Autoconf | For configuring the source package |
-   | common | build | yes | GNU Autoconf Archive | For configuring the source package |
-   | common | build | yes | GNU Automake | For generating makefiles |
-   | common | build | yes | GNU Make | For building the code |
-   | common | build | yes | `pkgconf` / `pkg-config` | For configuring build dependencies |
-   | common | test | optional | Check | For running unit tests |
-   | common | test | optional | Expat | For validating XML output |
-   | common | test | optional | GNU Groff | For checking man page documentation |
-   | Linux | build | optional | `libapparmor` development package | For AppArmor details |
-   | Linux | build | optional | `libcap` development package | For capabilities details |
-   | Linux | build | optional | `libnuma` development package | For NUMA memory details |
-   | Linux | build | optional | `libselinux` development package | For SELinux details |
-   | BSD | build | optional | `libsysinfo` package or port | For general memory details |
-
-   > **Note:**
-   >
-   > The definitive list of dependenciese can always be seen by looking at the GitHub Actions workflow file here:
-   >
-   > - [`.github/workflows/build.yaml`](.github/workflows/build.yaml)
-
-1. Checkout the source code:
-
-   ```bash
-   $ git clone https://github.com/jamesodhunt/procenv
-   $ cd procenv
-   ```
-
-1. Configure and build:
-
-   ```bash
-   $ autoreconf -fi && ./configure
-   $ make && make check && sudo make install
-   ```
-
-   > **Note:**
-   >
-   > For BSD systems, replace `make` with `gmake` above to ensure you run using
-   > GNU Make (BSD make will hang at the test stage!)
-
 ## Results
 
 `procenv` is extremely useful for learning about the environment