osmith has uploaded this change for review. ( https://gerrit.osmocom.org/c/osmo-dev/+/43641?usp=email )
Change subject: README: modernize ......................................................................
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/...) +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.