Add development documentation

Signed-off-by: Michael Buesch <[email protected]>

COMPATIBILITY.md

@@ -1,5 +1,4 @@
-Awlsim - STEP 7 compatibility
-=============================
+# Awlsim - STEP 7 compatibility
 
 The execution of AWL/STL programs by Awlsim is supposed to be fully compatible with the execution of compiled AWL/STL programs on the real Siemens S7 CPU. However, there currently are some known differences. These are listed below. Any undocumented difference between Awlsim and STEP 7 is considered to be a bug that should be reported.
 
@@ -14,8 +13,7 @@ The execution of AWL/STL programs by Awlsim is supposed to be fully compatible w
 * Undefined behavior is not emulated. For example: If reading uninitialized L-stack space in STEP 7 always yields a certain reproducible result, that does not mean that this AWL/STL code does the same thing in Awlsim. Reading uninitialized `TEMP`-memory is undefined.
 
 
-Awlsim extensions
-=================
+# Awlsim extensions
 
 Extensions are features that Awlsim supports, but STEP 7 does not support.
 

DEVELOPMENT.md

@@ -0,0 +1,33 @@
+# Awlsim development notes
+
+
+## Unit tests
+
+The unit test suite can be run with the invocation of the command `./tests/run.sh`. This will run all unit tests and show the results.
+Please see `./tests/run.sh --help` for more options.
+
+
+### Code coverage tracing
+
+To run a code statement coverage trace during unit testing the option `./tests/run.sh --coverage` is available. The results will be stored in `./code-coverage-report/`. It is desired to have a reasonable code coverage of the unit tests. All main code paths should be covered.
+
+
+## Special annotations in the source code
+
+In order to support both compiling the Awlsim core with Cython and running the same code in a plain Python interpreter without compilation, a method to patch the files is required. The setup.py scrips patch each .py source file and create a .pyx file before starting Cython compilation. The Cython patching mechanism rewrites all `import`s to import the compiled Cython modules instead of the plain Python modules. In addition to that some special comments are provided as hint to the Cython patcher:
+
+* `#@cy` : Enable (un-comment) this line during Cython patching.
+* `#@cy2` : Enable (un-comment) this line during Cython patching, if compiling for Python 2.
+* `#@cy3` : Enable (un-comment) this line during Cython patching, if compiling for Python 3.
+* `#@nocy` : Disable (comment) this line during Cython patching.
+* `#@no-cython-patch` : Do not touch this line during cython patching.
+* `#+NoneToNULL` : Transform all `None` keywords in this line into `NULL`.
+* `#+cimport` : Transform all `import` keywords in this line into `cimport`.
+* `#+cdef` : Add a `cdef` to this line. For functions or methods that means to change `def` into `cdef` in the function signature. For classes that means to change `class` to `cdef class`.
+* `#+cpdef` : Same as `#+cdef`, but add `cpdef` instead.
+* `#+cdef-foobar-bizz` : Same as `#+cdef`, but also add the additional words `foobar bizz` after `cdef`. Arbitrary words may be specified and the number of words is not limited. The dash `-` will be transformed into a space character.
+
+To disable code coverage tracing an additional special comment is provided:
+
+* `#@nocov` : This excludes the line from Python `coverage` tracing.
+

MANIFEST.in

@@ -16,6 +16,8 @@ graft tests
 include COMPATIBILITY.html
 include COMPATIBILITY.md
 include COPYING.txt
+include DEVELOPMENT.html
+include DEVELOPMENT.md
 include QUICK-START.html
 include QUICK-START.md
 include README.html

QUICK-START.md

@@ -1,5 +1,4 @@
-Awlsim - Quick start tutorial
-=============================
+# Awlsim - Quick start tutorial
 
 
 Start the GUI by invoking `awlsim-gui` on Linux, `awlsim-win.cmd` on Windows or `awlsim.cmd` on Windows (Awlsim standalone package). The following screen will appear:

README.md

@@ -1,13 +1,11 @@
-Awlsim - S7 compatible Programmable Logic Controller (PLC/SPS)
-==============================================================
+# Awlsim - S7 compatible Programmable Logic Controller (PLC/SPS)
 
 Awlsim is a free Step 7 compatible Programmable Logic Controller, that supports the automation languages AWL/STL and FUP/FBD. Awlsim itself is written in Python.
 
 The latest version of Awlsim can be downloaded at the [official Awlsim site](https://awlsim.de).
 
 
-Awlsim - Programmable Logic Controller (PLC/SPS)
-------------------------------------------------
+## Awlsim - Programmable Logic Controller (PLC/SPS)
 
 Awlsim is a free Step 7 compatible Programmable Logic Controller, that supports the automation languages AWL/STL and FUP/FBD. Awlsim itself is written in Python. The speed of execution ranges from several ten thousand AWL/STL instructions per second on slow embedded machines to a couple of million instructions per second on faster computers.
 
@@ -16,20 +14,17 @@ AWL/STL programs on PLCs are used for automation of industrial processes. Howeve
 Awlsim can emulate CPUs with two and four accumulator registers (S7-3xx and S7-4xx). Compatibility to S7 hardware is a task taken seriously by the Awlsim project. We want to be as close as possible to the real PLC hardware with our AWL/STL code execution. For this reason Awlsim ships an extensive selftest suite. Missing features and differences between Awlsim and Step 7 are documented in the [COMPATIBILITY documentation](COMPATIBILITY.html) and [TODO documentation](TODO.html) files.
 
 
-Quick start tutorial
---------------------
+## Quick start tutorial
 
 See the [quick start tutorial](QUICK-START.html) for a simple example on how to use Awlsim in simulator mode. In simulator mode Awlsim can be run on any desktop PC. No special hardware is required.
 
 
-Example project
----------------
+## Example project
 
 If you don't know where to start, you can find an example project in the `examples` directory as `EXAMPLE.awlpro`. You can easily run this example in simulation mode without the need for special hardware.
 
 
-Git repository
---------------
+## Git repository
 
 The latest development version of Awlsim can be fetched with git:
 
@@ -45,8 +40,7 @@ After cloning the main repository the git submodules must also be fetched. The f
 </pre>
 
 
-Dependencies
-------------
+## Dependencies
 
 Awlsim depends on [Python](https://python.org) 3.4 or later or alternatively Python 2.7.
 
@@ -68,8 +62,7 @@ pip3 install --upgrade Cython
 </pre>
 
 
-Directory structure
--------------------
+## Directory structure
 
 The Awlsim Git repository and source archive `awlsim-x.yz.tar.bz2` contain lots of files and directories. Here is an overview of the main files and directories and their purpose:
 
@@ -95,6 +88,7 @@ These files and directories contain useful information about Awlsim.
   examples/                 : Various example projects and feature demonstrations.
   COMPATIBILITY.md|html     : S7 compatibility documentation.
   COPYING.txt               : Main license.
+  DEVELOPMENT.md|html       : How to enhance and develop Awlsim.
   QUICK-START.md|html       : Quick start tutorial.
   README.md|html            : Main README document.
   TODO.md|html              : TODO list.
@@ -150,14 +144,12 @@ The hardware modules are the glue between the Awlsim core and the real world. Th
 </pre>
 
 
-FUP - Funktionsplan - Function block diagram
---------------------------------------------
+## FUP - Funktionsplan - Function block diagram
 
 Awlsim supports programming in an S7-FUP like language. See [the FUP documentation](doc/fup/FUP.html) for more information about Awlsim's implementation of FUP.
 
 
-Building Awlsim
----------------
+## Building Awlsim
 
 Awlsim can be run from the source directory in interpreted Python mode without building it. Just `cd` into the Awlsim source directory and execute the desired main executable (e.g. `./awlsim-gui` or `./awlsim-server` etc...).
 
@@ -168,8 +160,7 @@ For convenience there also is a helper script `./maintenance/build.sh`, which wi
 There also is `./maintenance/build-noopt.sh`. That builds Cython modules without optimization. The build is much faster, but the resulting Cython libraries will be much slower. This is useful for development. Do not use this for production.
 
 
-Building Debian / Raspbian / PiLC .deb packages
------------------------------------------------
+## Building Debian / Raspbian / PiLC .deb packages
 
 Installing or upgrading Awlsim on a Debian based system is easy.
 The `debuild` can be used to build the .deb packages. Just run the following commands to build all Awlsim .deb packages:
@@ -192,15 +183,12 @@ this can be fixed by re-installing the libc development package:
 `sudo apt install --reinstall libc-dev`
 
 
-Unit tests
-----------
+## Development
 
-The unit test suite can be run with the invocation of the command `./tests/run.sh`. This will run all unit tests and show the results.
-Please see `./tests/run.sh --help` for more options.
+Information about Awlsim development can be found in [the Awlsim development documentation](DEVELOPMENT.html).
 
 
-License / Copyright
--------------------
+## License / Copyright
 
 Copyright (C) Michael Büsch / et al.
 

TODO.md

@@ -1,42 +1,35 @@
-Incomplete awlsim TODO list
-===========================
+# Incomplete awlsim TODO list
 
-S7 compatibility
-----------------
+## S7 compatibility
 
 * Add feature: Parsing of attributes
 
-core
-----
+## core
 
 * Improve performance (cython)
 * Blocks that are no longer linked to (created by) sources should be removed.
 * Single download of symtab causes a redefinition error.
 * Add feature: LAD (KOP) compiler
 
-AWL / STL optimizer
--------------------
+## AWL / STL optimizer
 
 * Add optimization pass: O(UU)O(UU) -> UUOUU
 * Add optimization pass: U(UU)= -> UU=  (also for other insn types)
 * Add optimization pass: Reordering of TEMP variables for space packing
 
-GUI
----
+## GUI
 
 * Add feature: Save window status (open MDI windows, positions, etc)
 * Add feature: Show UDTs in block tree
 * Add feature: LAD (KOP) editor
 
-FBD/FUP GUI only
-----------------
+## FBD/FUP GUI only
 
 * Add feature: Exchange elements
 * Add feature: Live view of signal states (online diagnosis)
 * Add feature: Support modifying wires by clicking onto them
 
-FBD/FUP compiler and GUI
-------------------------
+## FBD/FUP compiler and GUI
 
 * Fix evaluation order in case of multiple parallel assignments and other elements
 * Add feature: Add option to disable elements