neels has uploaded this change for review. ( https://gerrit.osmocom.org/c/osmo-dev/+/43645?usp=email )

Change subject: README tweaks ......................................................................

README tweaks

Change-Id: I6e5fc98a42f50aa971f7750ccd6baafed2d83ec9 --- M README.md 1 file changed, 49 insertions(+), 23 deletions(-)

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

diff --git a/README.md b/README.md index af26d84..5ac8062 100644 --- a/README.md +++ b/README.md @@ -3,18 +3,18 @@ ## 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. +projects such as Open5GS) from source with a top-level Makefile produced by +`gen_makefile.py`. This is described in more detail below.

### Additional scripts

-* `net`: quickly configure, launch and tear down an entire Osmocom core network +* `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`). +* `src/`: scripts to sync local git clones with upstream gerrit (see `src/README`).

* `osmo-uninstall.sh`: remove installed binaries, libraries and headers from a given prefix, the default is `/usr/local`. @@ -63,7 +63,19 @@

### Make targets

-Other make targets exist for specific use cases: +Single projects can be built by name. The following example builds only +libosmo-abis, and its dependencies libosmocore and libosmo-netif: + +``` +make libosmo-abis +``` +This can be used for any project in `all.deps`, e.g. `make osmo-msc`, `make +osmo-bsc` etc. + +Top-level make targets exist for specific use cases: + +* `cn`: core network components: OsmoMSC, OsmoSGSN, osmo-iuh, OsmoGGSN, OsmoHLR, OsmoMGW, + OsmoSIPConnector, OsmoSMLC, including all of their dependencies.

* `usrp`: Build the CN, OsmoBSC, OsmoBTS and OsmoTRX (default, e.g. when connecting @@ -72,29 +84,34 @@ * `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`. +* You will find many other (hidden) `.make.*` files under src/. These control + the top-level Makefile: removing a file makes sure that the given step is + rebuilt, including all of its dependencies. + For example, if you `rm .make.libosmocore.autoconf`, libosmocore and all + projects depending on libosmocore will be rebuilt from scratch.

-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. +### Modify configuration + +If you modify the `all.deps` or `*.opts` file, update your `make*` subdir with: + +``` +make regen +``` + +This keeps the options intact that were first passed to `gen_makefile.py`. +(They are listed near the top of the generated `make*/Makefile`, convienient to +edit.)

### Configuration files

### all.deps

Whitespace-separated listing of: + ``` project_name depends_on_project_1 depends_on_project_2 ... ``` @@ -103,6 +120,7 @@

Projects that are not developed at `gerrit.osmocom.org/$project` are listed here in the following format: + ``` project_name URL ``` @@ -111,6 +129,7 @@

Projects that are not using `autotools` need an entry in this file in the form of: + ``` project_name BUILDSYSTEM ``` @@ -131,10 +150,14 @@ 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`. +Options can be added to all `./configure` steps of builds that use `autotools` +using the `ALL` keyword, for example: + +``` +ALL --prefix=/usr +``` + +(Note that `./configure` just ignores any options it does not understand.)

Find more information about specific `*.opts` files below.

@@ -179,7 +202,10 @@ export PATH="$PATH:/usr/local/bin" ```

+WARNING: setting `LD_LIBRARY_PATH` can have adverse effects. + ### 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. +osmo-trx is never built with the address sanitizer enabled. If you intend to +build osmo-trx, you should not use sanitize.opts, because linking a +sanitizer-enabled libosmocore will not work.