osmith submitted this change.
README: update
* Convert to markdown
* Add a short summary on top
* Modernize installation instructions
* Change the example from deprecated openbsc and deprecated
osmodumpdoc.py to libosmocore's osmo-ns-dummy and osmotestconfig.py
* Remove mention of twisted_ipa.py, as it was removed in 5d0fac9d
Change-Id: I13c6327ca210e29cde3f9bb75c93c892682a5a28
---
D README
A README.md
2 files changed, 89 insertions(+), 47 deletions(-)
diff --git a/README b/README
deleted file mode 100644
index 3b59257..0000000
--- a/README
+++ /dev/null
@@ -1,47 +0,0 @@
-Building/installation:
-
- sudo python3 setup.py install
-
-If you prefer to have it cleanly removable, install checkinstall and run
-
- sudo checkinstall python setup.py install
-
-Alternatively, just run
-
- pip3 install --user -e ./
-
-depending on your python version.
-
-Use:
-There are currently following scripts in this package:
-osmotestconfig.py - test that apps start/write with example configs
-osmo_trap2cgi.py - implementation of CGI <-> Ctrl proxy implemented on top of asyncio and aiohttp
-osmo_rate_ctr2csv.py - rate counter dumper on top of osmo_ipa
-osmo_interact_vty.py - pipe stdin/stdout to a VTY session
-osmo_interact_ctrl.py - pipe stdin/stdout to a CTRL port
-osmo_verify_transcript_vty.py - VTY testing by VTY session screen dumps
-osmo_verify_transcript_ctrl.py - CTRL testing by CTRL session script files
-twisted_ipa.py - implementation of IPA and Ctrl protocols on top of Twisted framework
-osmodumpdoc.py - dump documentation, superseded by osmo_interact_vty.py -X
-osmotestvty.py - test vty operations, superseded by osmo_verify_transcript_vty.py
-
-Some of these scripts import a project-specific osmoappdesc.py,
-which provides information about the available apps, configs, vty ports, etc.
-and is provided by other source trees (like osmo-bsc.git, osmo-msc.git, ...)
-
-Run the scripts with osmoappdesc.py in the current directory (preferred)
-or with -p <the directory containing osmoappdesc.py>.
-Remember that osmoappdesc.py may contain relative paths.
-
-Example:
-After install osmodumpdoc for openbsc's apps can be run by:
-cd <your_source_dir>/openbsc/openbsc && osmodumpdoc.py
-
-Libraries:
-osmopy/osmoutil.py - code that's shared between the scripts
-osmopy/osmo_ipa.py - generic implementation of IPA and Ctrl protocols in python
-osmopy/trap_helper.py - generic Trap class and related helpers used by soap.py and ctrl2cgi.py
-osmopy/osmo_interact/{vty,ctrl}.py - general interactions with VTY and CTRL ports
-osmopy/obscvty.py - connect to a vty, superseded by osmo_interact/vty
-
-obscvty.py may be of general use. osmoutil.py probably isn't.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b5d9959
--- /dev/null
+++ b/README.md
@@ -0,0 +1,89 @@
+# osmo-python-tests
+
+Various scripts that are mostly used for interacting with VTY/CTRL interfaces
+of Osmocom programs.
+
+## Installation
+
+### Python user install directory
+
+While discouraged by the python developers, the easiest way to make
+osmo-python-tests always available for your user is installing to
+`~/.local/lib/python3.*/site-packages/osmopy`:
+
+```
+$ pip3 install --user --break-system-packages .
+```
+
+### Virtual environment
+
+If you prefer to have osmo-python-tests clearly separated, install to a venv:
+
+```
+$ python3 -m venv ~/.osmocom-venv
+$ source ~/.osmocom-venv/bin/activate
+$ pip3 install .
+```
+
+Keep in mind that you must run the source line again whenever you need to use
+osmo-python-tests.
+
+### Osmocom binary packages
+
+If you run a Debian-based Linux distribution, you can alternatively enable the
+[Osmocom binary repository](https://osmocom.org/projects/cellular-infrastructure/wiki/Binary_Packages)
+and do a system-wide installation:
+
+```
+# apt install osmo-python-tests
+```
+
+## Usage
+
+There are currently following scripts in this package:
+
+* `osmotestconfig.py` - test that apps start/write with example configs
+* `osmo_trap2cgi.py` - implementation of CGI <-> Ctrl proxy implemented on top of asyncio and aiohttp
+* `osmo_rate_ctr2csv.py` - rate counter dumper on top of osmo\_ipa
+* `osmo_interact_vty.py` - pipe stdin/stdout to a VTY session
+* `osmo_interact_ctrl.py` - pipe stdin/stdout to a CTRL port
+* `osmo_verify_transcript_vty.py` - VTY testing by VTY session screen dumps
+* `osmo_verify_transcript_ctrl.py` - CTRL testing by CTRL session script files
+* `osmodumpdoc.py` - dump documentation, superseded by `osmo_interact_vty.py -X`
+* `osmotestvty.py` - test vty operations, superseded by `osmo_verify_transcript_vty.py`
+
+Some of these scripts import a project-specific `osmoappdesc.py`, which
+provides information about the available apps, configs, vty ports, etc. and is
+provided by other source trees (like osmo-bsc.git, osmo-msc.git, ...).
+
+Run the scripts with `osmoappdesc.py` in the current directory (preferred) or
+with `-p <the directory containing osmoappdesc.py>`. Remember that
+`osmoappdesc.py` may contain relative paths.
+
+### Example
+
+Build osmo-ns-dummy from libosmocore:
+
+```
+$ cd libosmocore
+$ autoreconf -fi
+$ ./configure
+$ make
+```
+
+Enter the directory with `osmoappdesc.py` and run a test script:
+
+```
+$ cd tests/gb
+$ osmotestconfig.py -w .
+```
+
+## Libraries
+
+* `osmopy/osmoutil.py` - code that's shared between the scripts
+* `osmopy/osmo_ipa.py` - generic implementation of IPA and Ctrl protocols in python
+* `osmopy/trap_helper.py` - generic Trap class and related helpers used by `soap.py` and `ctrl2cgi.py`
+* `osmopy/osmo_interact/{vty,ctrl}.py` - general interactions with VTY and CTRL ports
+* `osmopy/obscvty.py` - connect to a vty, superseded by `osmo_interact/vty.py`
+
+`obscvty.py` may be of general use. `osmoutil.py` probably isn't.
To view, visit change 43101. To unsubscribe, or for help writing mail filters, visit settings.