doc: cleanup and refactor structure

Signed-off-by: Markus Klotzbuecher <mk@mkio.de>

docs/source/composing_systems.rst

@@ -1,4 +1,30 @@
 Composing microblx systems
 ==========================
 
+To build a microblx application, blocks need to be instantiated,
+configured, connected and started up according to the life-cycle
+FSM. There are different ways to do this:
+
+- by using microblx system composition files (the ``*.usc`` files
+  under examples). ``usc`` stands for microblx system
+  composition). These can be launched using the ``ubx_launch``
+  tool. For example:
+
+.. code:: bash
+
+   $ ubx_launch -webif -c examples/trig_rnd_hexdump.usc
+ 
+  this will launch the given system composition and additionally
+  create a webserver block to allow system to be introspected via a
+  browser. Using the usc files is the preferred approach.
+
+- by writing a Lua called “deployment script” (e.g. see
+  ``examples/trig_rnd_to_hexdump.lua``). This is not recommended under
+  normal circumstances, but can be useful in specific cases such as
+  for building dedicated test tools.
+
+- by assembling everything in C/C++. Possible, but somewhat painful to
+  do by hand. This would be better solved by introducing a
+  usc-compiler tool.
+
 

docs/source/developing_blocks.rst

@@ -1,10 +1,10 @@
 Developing microblx blocks
 ==========================
 
-The following is based on the (heavily documented random number
-generator block (``std_blocks/random/``).
+Overview
+----------
 
-Building a block entails the following:
+Generally, building a block entails the following:
 
 1. declaring configuration: what is the static configuration of a block
 2. declaring ports: what is the input/output of a block
@@ -21,6 +21,14 @@ Building a block entails the following:
 7. registration of blocks and types: make block prototypes and types
    known to the system
 
+The following describes these steps in detail and is based on the
+(heavily) documented random number generator block
+(``std_blocks/random/``).
+
+Note: Instead of manually implementing the above, a tool
+``ubx_genblock`` is available which can generate blocks including
+interfaces from a simple description. See `Block code-generation`_.
+
 Declaring configuration
 -----------------------
 
@@ -384,47 +392,65 @@ http://spdx.org/licenses/ http://spdx.org
 Block code-generation
 ~~~~~~~~~~~~~~~~~~~~~
 
-The script ``tools/ubx_genblock.lua`` generates a microblx block
-including a makefile. After this, only the hook functions need to be
-implemented in the ``.c`` file:
+The ``ubx_genblock`` tool generates a microblx block including a
+Makefile. After this, only the hook functions need to be implemented
+in the ``.c`` file:
 
 Example: generate stubs for a ``myblock`` block (see
 ``examples/block_model_example.lua`` for the block generator model).
 
-.. code:: bash
+.. code:: sh
+
+   $ ubx_genblock -d myblock -c /usr/local/share/ubx/examples/blockmodels/block_model_example.lua
+       generating myblock/bootstrap
+       generating myblock/configure.ac
+       generating myblock/Makefile.am
+       generating myblock/myblock.h
+       generating myblock/myblock.c
+       generating myblock/myblock.usc
+       generating myblock/types/vector.h
+       generating myblock/types/robot_data.h
+
+Run ``ubx_genblock -h`` for full options.
+
+The following files are generated:
 
-   $ tools/ubx_genblock.lua -c examples/block_model_example.lua -d std_blocks/test
-       generating std_blocks/test/Makefile
-       generating std_blocks/test/myblock.h
-       generating std_blocks/test/myblock.c
-       generating std_blocks/test/myblock.usc
-       generating std_blocks/test/types/vector.h
-       generating std_blocks/test/types/robot_data.h
+-  ``bootstrap`` autoconf bootstrap script
+-  ``configure.ac`` autoconf input file
+-  ``Makefile.am`` automake input file
+-  ``myblock.h`` block interface and module registration code (don’t edit)
+-  ``myblock.c`` module body (edit and implement functions)
+-  ``myblock.usc`` simple microblx system composition file, see below (can be extended)
+-  ``types/vector.h`` sample type (edit and fill in struct body)
+-  ``robot_data.h`` sample type (edit and fill in struct body)
 
-If the command is run again, only the ``.c`` file will be NOT
+
+If the command is run again, only the ``.c`` file will NOT be
 regenerated. This can be overriden using the ``-force`` option.
+
+
+Compile the block
+~~~~~~~~~~~~~~~~~
 
-Assembling blocks
------------------
+.. code:: sh
 
-There are different options how to create a system from blocks:
+   $ cd myblock/
+   $ ./bootstrap
+   $ ./configure
+   $ make
+   $ make install
 
--  by using a declarative description of the desired composition (the
-   ``*.usc`` files under examples). ``usc`` stands for microblx system
-   composition). These can be launched using the ``ubx_launch`` tool,
-   e.g.
+Launch block using ubx_launch
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. code:: bash
+.. code:: sh
 
-   $ tools/ubx_launch -webif -c examples/trig_rnd_hexdump.usc
+   $ ubx_ilaunch -webif -c myblock.usc
 
-this will launch␇the given system composition and additionally create a
-webserver block to allow system to be introspected.
+Run ``ubx_launch -h`` for full options.
 
--  by writing a so called “deployment script” (e.g. see
-   ``examples/trig_rnd_to_hexdump.lua``)
+Browse to http://localhost:8888
 
--  by assembling the necessary parts in C.
 
 Tips and Tricks
 ---------------
@@ -455,7 +481,7 @@ What the difference between block types and instances?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 First: to create a block instance, it is cloned from an existing block
-and the ``block->prototype`` char ponter set to a newly allocated string
+and the ``block->prototype`` char pointer set to a newly allocated string
 holding the protoblocks name.
 
 There’s very little difference between prototypes and instances:
@@ -472,3 +498,5 @@ Module visibility
 
 The default Makefile defines ``-fvisibility=hidden``, so there’s no need
 to prepend functions and global variables with ``static``
+
+

docs/source/introduction.rst → docs/source/getting_started.rst

@@ -1,10 +1,13 @@
-Introduction
-============
+Getting started
+===============
 
-Microblx is a lightweight function block model and implementation.
 
-Key concepts
-------------
+Overview
+--------
+
+Microblx is a very lightweight function block model and
+implementation.
+
 
 - **block**: the basic building block of microblx. Is defined by filling in a
   ``ubx_block_t`` type and registering it with a microblx
@@ -43,29 +46,30 @@ Installation
 Dependencies
 ~~~~~~~~~~~~
 
- - uthash (apt: ``uthash-dev``)
- - luajit (>=v2.0.0) (apt: ``luajit`` and ``libluajit-5.1-dev``) (not
+- uthash (apt: ``uthash-dev``)
+- luajit (>=v2.0.0) (apt: ``luajit`` and ``libluajit-5.1-dev``) (not
    strictly required, but recommended)
- - ``uutils`` Lua modules [github](https://github.com/kmarkus/uutils)
- - ``liblfds`` lock free data structures (v6.1.1) [github](https://github.com/liblfds/liblfds6.1.1)
- - ``lua-unit`` (apt: ``lua-unit``, src:
-   [luaunit](https://github.com/bluebird75/luaunit) (to run the tests)
- - gcc or clang
- - only for development: ``cproto`` (apt: ``cproto``) to generate C prototype header file
- - autotools etc. (apt: ``automake``, ``libtool``, ``pkg-config``, ``make``)
+- ``uutils`` Lua utilities `git <https://github.com/kmarkus/uutils>`_
+- ``liblfds`` lock free data structures (v6.1.1) `git <https://github.com/liblfds/liblfds6.1.1>`_
+- autotools etc. (apt: ``automake``, ``libtool``, ``pkg-config``, ``make``)
+
+Only for microblx development:
+
+- ``lua-unit`` (apt: ``lua-unit``, `git <https://github.com/bluebird75/luaunit>`_) (to run the tests)
+- ``cproto`` (apt: ``cproto``) to generate C prototype header file
 
 Building and setting up
-------------------------
+~~~~~~~~~~~~~~~~~~~~~~~
 
 Using yocto
-~~~~~~~~~~~
+^^^^^^^^^^^
 
 The best way to use microblx on an embedded system is by using the
-[meta-microblx](https://github.com/kmarkus/meta-microblx) yocto
+`meta-microblx <https://github.com/kmarkus/meta-microblx>`_ yocto
 layer. Please see the README in that repository for further steps.
 
 Building manually
-~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^
 
 Building to run locally on a PC.
 
@@ -116,11 +120,38 @@ Now build microblx:
 Quickstart
 ----------
 
-Run the example system:
 
-```bash
-$ ubx_ilaunch -webif -c /usr/share/microblx/examples/systemmodels/trig_rnd_hexdump.usc
-```
-browse to http://localhost:8888 to inspect the system.
+NOTE: the following assume microblx was installed in the default
+locations under ``/usr/local/``. If you installed it in a different
+location you will need to adopt the path to the examples.
+
+Run the random block example
+----------------------------
+
+This (silly) example creates a random number generator block. It’s
+output is hexdump’ed (using the ``hexdump`` interaction block) and also
+logged using a ``file_logger`` block.
+
+Before launching the composition, it is advisable to run the logging
+client to see potential errors:
+
+::
+
+   $ ubx_log
+
+and then in another terminal:
+
+.. code:: sh
+
+   $ ubx_ilaunch -webif -c /usr/local/share/ubx/examples/systemmodels/trig_rnd_hexdump.usc
+
+Browse to http://localhost:8888
+
+Explore:
+
+1. clicking on the node graph will show the connections
+2. clicking on blocks will show their interface
+3. start the ``file_log1`` block to enable logging
+4. start the ``ptrig1`` block to start the system.
 
 

docs/source/index.rst

@@ -10,7 +10,7 @@ Welcome to microblx's documentation!
    :maxdepth: 2
    :caption: Contents:
 
-   introduction.rst
+   getting_started.rst
    developing_blocks.rst
    composing_systems.rst
    tutorial.rst