README: modernize

Change-Id: Ie653062d43c486ce977ed772f0d06f0199952188
---
D README
A README.md
A ttcn3/tmux/README.md
3 files changed, 191 insertions(+), 156 deletions(-)


git pull ssh://gerrit.osmocom.org:29418/osmo-dev refs/changes/41/43641/1

diff --git a/README b/README
deleted file mode 100644
index e425c8e..0000000
--- a/README
+++ /dev/null
@@ -1,156 +0,0 @@
-=== WHAT IS THIS?
-
-* quickly build the entire Osmocom core network stack from source, with a
-  generated top-level makefile (see the rest of this README file below).
-
-* quickly configure, launch and tear down an entire Osmocom core network on
-  your box (see net/README).
-
-
-=== Quick Start
-
-sudo apt install \
-  build-essential gcc g++ make automake autoconf libtool pkg-config \
-  libtalloc-dev libpcsclite-dev libortp-dev libsctp-dev libssl-dev libdbi-dev \
-  libdbd-sqlite3 libsqlite3-dev libpcap-dev libc-ares-dev libgnutls28-dev \
-  libsctp-dev sqlite3 libusb-1.0-0-dev libmnl-dev libsofia-sip-ua-glib-dev
-
-./gen_makefile.py default.opts iu.opts no_dahdi.opts -I -m make
-
-cd make
-make
-
-- 'make' will ask for sudo password to run 'make install' and 'ldconfig'.
-  To run non-interactively:
-
-  - 'make install':
-    chown $USER: /usr/local
-    Then call gen_makefile.py once without the -I option
-
-  - 'ldconfig':
-    echo "$USER  ALL= NOPASSWD: /sbin/ldconfig" > /etc/sudoers.d/ldconfig
-
-
-=== gen_makefile.py
-
-This provides a set of top-level makefiles to build variants of the Osmocom
-source trees. It is inteded for the core network components and related
-projects, but works generically.
-
-The idea is to have all your Osmocom git clones in ./src, while keeping one or
-more separate build trees in ./make-*.
-
-Run ./gen_makefile.py with a choice of choice of configure options.
-
-
-Examples:
-
-CN with full 2G and 3G support:
-
-  ./gen_makefile.py default.opts iu.opts -m make
-  cd make
-  make cn
-
-Other make targets exist for specific use cases:
-
-  - 'usrp':
-    Build the CN, OsmoBSC, OsmoBTS and OsmoTRX (default, e.g. when connecting
-    to an USRP)
-
-  - 'cn-bsc':
-    Build the CN and OsmoBSC (e.g. when connecting to an external sysmoBTS)
-
-  - 'osmo-msc':
-    Build only the OsmoMSC project and its dependencies (this can be used for
-    any project in all.deps).
-
-  - '.make.osmo-ttcn3-hacks.clone'
-    Clone the osmo-ttcn3-hacks git repository (it cannot be built by osmo-dev,
-    but cloning it is still useful.)
-
-If you make modifications in one of the source trees, this Makefile will pick
-it up, rebuild the project and also rebuild all dependencies (according to
-all.deps).
-
-If you modify the all.deps or *.opts file, you can easily run 'make regen' in a
-make-* subdir to regenerate the Makefile from the same files.
-
-In your make-* subdir there are empty status files that are touched for every
-completed make target. From these, 'make' can detect what needs to be rebuilt.
-You can manually remove them to force a rebuild of a specific target.
-
-For example, if you 'rm .make.libosmocore.autoconf', libosmocore and all
-projects depending on libosmocore will be rebuilt from scratch.
-
-For more details on the *.opts and all.deps syntax, read the docs at the top of
-./gen_makefile.py.
-
-It is also easily possible to keep sources and build trees in various
-configurations, see the command line options of ./gen_makefile.py.
-
-
-=== Install in /usr
-
-By default, the Osmocom install prefix is /usr/local, while (currently) the
-default systemd *.service files expect binaries installed in /usr/bin. To
-install in /usr instead, use prefix_usr.opts, which sets --prefix=/usr.
-
-
-=== Systemd Service Files
-
-If you encounter problems installing *.service files, no_systemd.opts may help:
-
-Systemd recommends installing service files in the distribution's single
-service file location; that may sound sane, but if that location is
-/lib/systemd/system, that means even a --prefix=/home/private/prefix ends up
-trying to install service files system-wide in /lib/systemd/system, making all
-attempts to install to a user-writable location fail.
-
-no_systemd.opts disables installing *.service files.
-
-
-=== Build Environment
-
-For dependencies, see the "External dependencies" on:
-
-  https://osmocom.org/projects/cellular-infrastructure/wiki/Build_from_Source
-
-If /usr/local/ is not writable by your user, pass the --sudo-make-install
-option to gen_makefile.py above (a custom --prefix is not yet supported).
-
-If your system doesn't have this by default, you will need:
-
-  export LD_LIBRARY_PATH="/usr/local/lib"
-
-and
-
-  export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig"
-
-to your environment. To use the installed binaries after installation, also
-
-  export PATH="$PATH:/usr/local/bin"
-
-
-=== osmo-uninstall.sh
-
-Remove osmocom built binaries and headers from given prefix,
-default is /usr/local.
-
-
-=== src/*
-
-Find other useful scripts in src/, see src/README.
-
-=== ttcn3/tmux
-
-It's possible to run TTCN-3 test cases without using Docker.  This directory
-contains scripts for starting a testsuite and the related binaries in a tmux
-session.  For example, ttcn3-bsc-test.sh does the following:
-
-* Starts osmo-bsc, osmo-stp, and three instances of osmo-bts-omldummy.
-* Prepares a command for execuring the test suite.
-
-=== Troubleshooting
-
-When using sanitize.opts, osmo-trx is not built with the address sanitizer
-enabled. Linking a sanitizer-enabled libosmocore will not work.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..af26d84
--- /dev/null
+++ b/README.md
@@ -0,0 +1,185 @@
+# osmo-dev
+
+## Overview
+
+The main purpose of this project is building the Osmocom stack (and related
+projects such as Open5GS) from source with `gen_makefile.py`. This is described
+in more detail below.
+
+### Additional scripts
+
+* `net`: quickly configure, launch and tear down an entire Osmocom core network
+  on your box (see `net/README`).
+
+* `ttcn3/tmux`: start a tmux session with a TTCN-3 testsuite and related
+  binaries (see `ttcn3/tmux/README.md`).
+
+* `src`: other useful scripts related to git and gerrit (see `src/README`).
+
+* `osmo-uninstall.sh`: remove installed binaries, libraries and headers from a
+  given prefix, the default is `/usr/local`.
+
+## `gen_makefile.py`
+
+This script generates a `Makefile` that was originally intended to build the
+Osmocom core network components, but has since been extended to also build
+Open5GS, PyHSS and more. See `all.deps` for a list of supported projects.
+
+The idea is to have all your git clones in `./src`, while keeping one or more
+separate build trees in `./make*` dirs.
+
+`gen_makefile.py` gets used by
+[`testenv.py`](https://gitea.osmocom.org/ttcn3/osmo-ttcn3-hacks/src/branch/master/_testenv/README.md)
+in `osmo-ttcn3-hacks.git` to build projects from source when running without
+the `--binary-repo` argument.
+
+### Dependencies
+
+Install required packages first. To have enough dependencies for building and
+installing most Osmocom programs, you can run this on Debian-based systems:
+
+```
+$ sudo apt install \
+  build-essential gcc g++ make automake autoconf libtool pkg-config \
+  libtalloc-dev libpcsclite-dev libortp-dev libsctp-dev libssl-dev libdbi-dev \
+  libdbd-sqlite3 libsqlite3-dev libpcap-dev libc-ares-dev libgnutls28-dev \
+  libsctp-dev sqlite3 libusb-1.0-0-dev libmnl-dev libsofia-sip-ua-glib-dev
+```
+
+### Example usage
+
+Build the Osmocom core network with full 2G and 3G support:
+
+```
+$ ./gen_makefile.py default.opts iu.opts no_dahdi.opts no_systemd.opts -I -m make
+$ cd make
+$ make cn
+```
+
+If you make modifications in one of the source trees, this `Makefile` will pick
+it up, rebuild the project and also rebuild all dependencies (according to
+`all.deps`). It is also easily possible to keep sources and build trees in
+various configurations, see the command line options of `gen_makefile.py`.
+
+### Make targets
+
+Other make targets exist for specific use cases:
+
+* `usrp`:
+  Build the CN, OsmoBSC, OsmoBTS and OsmoTRX (default, e.g. when connecting
+  to an USRP)
+
+* `cn-bsc`:
+  Build the CN and OsmoBSC (e.g. when connecting to an external sysmoBTS)
+
+* `osmo-msc`:
+  Build only the OsmoMSC project and its dependencies (this can be used for
+  any project in `all.deps`).
+
+* `.make.osmo-ttcn3-hacks.clone`:
+  Clone the osmo-ttcn3-hacks git repository (it cannot be built by osmo-dev,
+  but cloning it is still useful.)
+
+If you modify the `all.deps` or `*.opts` file, you can easily run `make regen`
+in a `make*` subdir to regenerate the `Makefile` from the same files, with the
+same options for `gen_makefile.py`.
+
+In your `make*` subdir there are empty status files that are touched for every
+completed make target. From these, `make` can detect what needs to be rebuilt.
+You can manually remove them to force a rebuild of a specific target. For
+example, if you `rm .make.libosmocore.autoconf`, libosmocore and all projects
+depending on libosmocore will be rebuilt from scratch.
+
+### Configuration files
+
+### all.deps
+
+Whitespace-separated listing of:
+```
+project_name depends_on_project_1 depends_on_project_2 ...
+```
+
+### all.urls
+
+Projects that are not developed at `gerrit.osmocom.org/$project` are listed
+here in the following format:
+```
+project_name    URL
+```
+
+### all.buildsystems
+
+Projects that are not using `autotools` need an entry in this file in the
+form of:
+```
+project_name    BUILDSYSTEM
+```
+
+Supported buildsystems are:
+* `autotools`
+* `cmake`
+* `erlang`
+* `meson`
+* `python`
+
+#### `*.opts` files
+
+The `*.opts` files provide options that are passed to `./configure`,
+`meson setup` and `cmake`. They have the following format:
+
+```
+project_name    OPTION(S)
+```
+
+If `project_name` is `ALL`, the option gets added to all projects using the
+`autotools` build system. This is because `./configure` just ignores any
+options it does not understand and initially only `autotools` was supported by
+`gen_makefile.py`.
+
+Find more information about specific `*.opts` files below.
+
+##### `prefix_usr.opts`
+
+By default, the Osmocom install prefix is `/usr/local`, while the systemd
+`*.service` files expect binaries installed in `/usr/bin`. To install to `/usr`
+instead, it is possible to add `prefix_usr.opts` to the `gen_makefile.py`
+arguments, which sets `--prefix=/usr`. Be aware that this will cause problems
+with distribution packages.
+
+##### `no_systemd.opts`
+
+`no_systemd.opts` disables installing `*.service` files, which is useful
+because these files get installed to `/usr/lib/systemd/system` even if the
+prefix is not `/usr`. Using `no_systemd.opts` is required for running
+`gen_makefile.py` without the `-I` (`--sudo-make-install`) argument.
+
+### Run without sudo prompts
+
+`make` will ask for the sudo password to run `make install` and `ldconfig`. To
+run non-interactively:
+
+```
+$ sudo chown -R $USER: /usr/local
+$ echo "$USER  ALL= NOPASSWD: $(command -v ldconfig)" | sudo tee /etc/sudoers.d/ldconfig
+```
+
+Then call `gen_makefile.py` once without `-I` (`--sudo-make-install`).
+
+## Troubleshooting
+
+### Environment variables
+
+If your system can't find installed libraries (e.g. if you run
+`gen_makefile.py` with `--no-ldconfig`), pkg-config files or binaries then
+setting these environment variables should help:
+
+```
+export LD_LIBRARY_PATH="/usr/local/lib"
+export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig"
+export PATH="$PATH:/usr/local/bin"
+```
+
+### sanitize.opts and osmo-trx
+
+When using sanitize.opts, osmo-trx is not built with the address sanitizer
+enabled. Linking a sanitizer-enabled libosmocore will not work.
diff --git a/ttcn3/tmux/README.md b/ttcn3/tmux/README.md
new file mode 100644
index 0000000..0d09976
--- /dev/null
+++ b/ttcn3/tmux/README.md
@@ -0,0 +1,6 @@
+It's possible to run TTCN-3 test cases without using Docker.  This directory
+contains scripts for starting a testsuite and the related binaries in a tmux
+session.  For example, ttcn3-bsc-test.sh does the following:
+
+* Starts osmo-bsc, osmo-stp, and three instances of osmo-bts-omldummy.
+* Prepares a command for execuring the test suite.

