Sphinx with Markdown Documentation - Release 0.1.0 Marijn van der Zee - cASTD
←
→
Page content transcription
If your browser does not render page correctly, please read the page content below
Sphinx with Markdown Documentation
Release 0.1.0
Marijn van der Zee
Mar 23, 2021
CONTENTS
1 Install Java Development Toolkit 3
1.1 Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2 Compile source code 5
3 Run cASTD 7
4 cASTD architecture 9
4.1 ASTD object model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4.2 IL model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4.3 Output structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
5 eASTD and cASTD integration 13
5.1 Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
6 Examples 17
6.1 Run spec from eASTD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
6.2 Run spec from command-line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
7 Technical documentation 23
8 Slack channel 25
iii
Sphinx with Markdown Documentation, Release 0.1.0 Unzip all files in the cASTD project. Next, execute the following commands. CONTENTS 1
Sphinx with Markdown Documentation, Release 0.1.0 2 CONTENTS
CHAPTER
ONE
INSTALL JAVA DEVELOPMENT TOOLKIT
1.1 Linux
~# sudo apt-get install build-essential
~# sudo add-apt-repository ppa:openjdk-r/ppa
~# sudo apt-get update
~# sudo apt-get install openjdk-8-jdk
~# sudo update-alternatives --config java
~# sudo update-alternatives --config javac
~# sudo apt-get install ant
1.2 Windows
• JAVA >= 1.8 : https://jdk.java.net/
• GCC >= 7.0
3Sphinx with Markdown Documentation, Release 0.1.0 4 Chapter 1. Install Java Development Toolkit
CHAPTER
TWO
COMPILE SOURCE CODE
~# ant
5Sphinx with Markdown Documentation, Release 0.1.0 6 Chapter 2. Compile source code
CHAPTER
THREE
RUN CASTD
~# java -jar castd.jar -v -h
OS version: linux
Build version 1.21
usage: cASTD [-c] [-d] [-e] [-f ] [-h] [-I
] [-k] [-L ] [-m ] [-o
] [-s ] [-v]
Options, flags and arguments may be in any order
-c,--condition-opt Condition optimization
-d,--debug Activate the debug mode
-e,--show-exec-state Show the execution state of
the input ASTD
-f,--format Use shorthand event format
or json event format or both
in the compiled program
-h,--help Display cASTD arguments and
their description
-I,--include Include custom headers
-k,--kappa-opt Kappa direct optimization
-L,--lib Include external libraries
-m,--main Name of main astd
-o,--output The output source and
executable code
-s,--spec The input specification
-v,--version The cASTD version
cASTD is a tool that helps to generate source and executable code in C++ from ASTD specifications.
7Sphinx with Markdown Documentation, Release 0.1.0 8 Chapter 3. Run cASTD
CHAPTER
FOUR
CASTD ARCHITECTURE
The compilation methodology is divided into 4 steps: parsing, translation from the ASTD language to the Intermediate
Model (IM), translation from the IM model to the target code, and code optimization. Several optimizations such as
removing redundant calculations are applied to the output code during the generation of the program.
Fig. 1: castd_architecture
4.1 ASTD object model
The first step reads an ASTD specification in JSON and produces an ASTD object model.
9Sphinx with Markdown Documentation, Release 0.1.0
Fig. 2: astd_object
4.2 IL model
The second step generates a program represented in an intermediate language. The last step translates an intermediate
model of the program into a concrete programming language like C++.
Fig. 3: il_model
10 Chapter 4. cASTD architectureSphinx with Markdown Documentation, Release 0.1.0
4.3 Output structure
cASTD takes a JSON spec and user files (e.g. *.cpp, *.h) as input, and generates a binary executable and C++
source code. For complex types and visualization of the execution state of the ASTD, you need a JSON library called
nlohmann. It is a sophisticated library to manipulate JSON documents. This library is automatically included when
using JSON event formats or types.
Fig. 4: castd
During the visualization of the execution state of an ASTD, with the option -e | -show-execution-state,
two other files are generated. The first one client.h allows sending the current execution state of an ASTD
to eASTD through a socket file. The second one exec_schema.h maps features in the JSON schema exec.
schema.json to their ID values.
4.3. Output structure 11Sphinx with Markdown Documentation, Release 0.1.0 12 Chapter 4. cASTD architecture
CHAPTER
FIVE
EASTD AND CASTD INTEGRATION
The ASTD project is a composition 3 different projects:
Which can all be installed separately. Refers to the page for
installation.
1. iASTD
2. cASTD
3. eASTD
5.1 Procedure
1. Start by downloading the install script. *Right-Click,
download. . . *. | install.py
2. Now at this point you should know the path of the install.py file.
If you don’t, it’s probably in your Downloads folder. I recommend you put the file where you want to install
ASTD (i.e. Desktop). | Now copy the file from the download folder ( or wherever you saved it ) to the location
you want.
3. Open a terminal and navigate to that location.
4. Launch the install script with python3.
python3 install.py.
5. If successful you should see this, if not refer to the trouble shooting version.
6. You should by now have a folder (astd) that contains 3 folder
• castd
• eASTD
• iASTD
7. You can now launch eASTD
*ATTENTION*
If you want castd to be functional with the editor you MUST put it
13Sphinx with Markdown Documentation, Release 0.1.0
in the astd folder along with other tools (i.e., iASTD, eASTD).
8. Load an ASTD example
Fig. 1: castd_example
9. Setup castd configuration from eASTD
10. Run cASTD from the eASTD editor
11. Visualize the execution state
cASTD can execute in interactive mode by manually entering events. It can also run from an event file.
14 Chapter 5. eASTD and cASTD integrationSphinx with Markdown Documentation, Release 0.1.0
Fig. 2: eastd_config
5.1. Procedure 15Sphinx with Markdown Documentation, Release 0.1.0
Fig. 3: castd_run
Fig. 4: castd_kleene
16 Chapter 5. eASTD and cASTD integrationCHAPTER
SIX
EXAMPLES
6.1 Run spec from eASTD
1. Load your *.eastd project or create a new spec in the eASTD editor.
2. Configures the cASTD execution and save your configuration following instructions in Section eASTD and
cASTD integration.
3. Run your spec in interactive mode by clicking the green button |>.
6.2 Run spec from command-line
After editing your spec in the eASTD editor, export it to JSON. Now, open a command-line following instructions in
Section Installation.
6.2.1 ASTD execution
Let us consider the test case tests/testcases/specs/Flow_Automaton.
Interactive mode
To compile this test case, run command
~# java -jar castd.jar -s tests/testcases/Flow_Automaton/*.json -o tests/testcases/
˓→Flow_Automaton/
[stage 1] Helper code generation succeeded ...
[stage 2] Main code generation succeeded ...
[stage 3] Makefile successfully generated ...
[Success] cASTD successfully generated code. Done !!!
~# ./main -h
This program has been compiled by cASTD.
./my_program [-i ] [-h]
[OPTIONS]
-i Read an event file in Shorthand format.
If an event file is not given, it runs in interactive
mode from command line
-h Show this help
~# ./main
e1(1)
e2(1)
(continues on next page)
17Sphinx with Markdown Documentation, Release 0.1.0
(continued from previous page)
val=2
e1(1)
e2(1)
val=4
e5(1)
Event is not recognized
e1("test")
Event is not executable
~#
This command generates a program with the default input event format shorthandevents. Note that since the
option -m is not specified, cASTD will execute the default astd MAIN.
To generate a program that can read a JSON event format, add the option -f json, i.e.
~# java -jar castd.jar -s tests/testcases/Flow_Automaton/*.json -o tests/testcases/
˓→Flow_Automaton/ -f json
[stage 1] Helper code generation succeeded ...
[stage 2] Main code generation succeeded ...
[stage 3] Makefile successfully generated ...
[Success] cASTD successfully generated code. Done !!!
~# ./main -h
This program has been compiled by cASTD.
./my_program [-i ] [-h]
[OPTIONS]
-i Read an event file in JSON format.
If an event file is not given, it runs in interactive
mode from command line
-h Show this help
~# ./main -i input.json
val=2
val=4
Event is not recognized
Event is not executable
As you see, the compiled program can take an input event file.
Using an input event file
To generate a program that can read either the shordhand event format or the JSON event format, add the option -f
all, i.e.
~# java -jar castd.jar -s tests/testcases/Flow_Automaton/*.json -o tests/testcases/
˓→Flow_Automaton/ -f all
[stage 1] Helper code generation succeeded ...
[stage 2] Main code generation succeeded ...
[stage 3] Makefile successfully generated ...
[Success] cASTD successfully generated code. Done !!!
~# ./main -h
This program has been compiled by cASTD.
./my_program [-i ] [-f ] [-h]
[OPTIONS]
-i Read an event file in JSON or Shorthand format.
If an event file is not given, it runs in interactive
mode from command line
-f Event format. It can be a JSON or Shorthand format
(continues on next page)
18 Chapter 6. ExamplesSphinx with Markdown Documentation, Release 0.1.0
(continued from previous page)
-h Show this help
~# ./main -i input.json -f json
val=2
val=4
Event is not recognized
Event is not executable
~# ./main -i input.txt -f shorthandevents
val=2
val=4
Event is not recognized
Event is not executable
6.2.2 If-fi optimization
To do if-fi optimization (see cASTD/doc), add argument --condition-opt | -c and run command
~# java -jar castd.jar -s tests/testcases/Flow_Automaton/*.json -o tests/testcases/
˓→Flow_Automaton/ -c
6.2.3 Kappa optimization
To do direct kappa optimization (see cASTD/doc), add argument --kappa-opt | -k and run command
~# java -jar castd.jar -s tests/testcases/Flow_Automaton/*.json -o tests/testcases/
˓→Flow_Automaton/ -c -k
Indirect kappa optimization is currently not supported.
6.2.4 Complex types
For complex types, the nlohmann JSON library automatically included (see Section cASTD architecture/Output struc-
ture). Let us consider the test case tests/testcases/Call. Run command
~# java -jar castd.jar -s tests/testcases/Call/*.json -o tests/testcases/Call/ -f json
It shows an example of network packet execution. The packet is encoded in JSON and it is decoded using the JSON
library during compilation.
~# java -jar castd.jar -s tests/testcases/Call/*.json -o tests/testcases/Call/ -f json
6.2.5 Visualization of the current state of an ASTD
To enable the visualization of the current state in the eASTD editor, add argument --show-state-activation
| -e in the command line.
Let us consider the test case tests/testcases/Automaton_Automaton. Run command
~# java -jar castd.jar -s tests/testcases/Automaton_Automaton/*.json -o tests/
˓→testcases/Automaton_Automaton/ -c -f all -m test -k -e
6.2. Run spec from command-line 19Sphinx with Markdown Documentation, Release 0.1.0
Then, execute the generated program with option -e and -v. The option -e allows one to send the current state of
the ASTD to eASTD using the socket file exectojson.sock. The option -v allows one to print out the current
execution state in JSON.
~# cat inputs.trace
e1(0)
e2(2)
e1("test")
~# ./test -h
This program has been compiled by cASTD.
./my_program [-i ] [-e ] [-v][-f ] [-h]
[OPTIONS]
-i Read an event file in JSON or Shorthand format.
If an event file is not given, it runs in interactive
mode from command line
-e Socket file to send the execution state to eASTD
-f Event format. It can be a JSON or Shorthand format
-v Print the current execution state in console (verbose)
-h Show this help
~# ./test -i inputs.trace -f shorthandevents -e exectojson.sock -v
Connection succeeded !
Sent event: {
"executed_event": "e1",
"top_level_astd": {
"attributes": [
{
"current_value": 0,
"name": "a",
"type": "int"
}
],
"current_state_name": "S1",
"current_sub_state": {
"attributes": [
{
"current_value": 0,
"name": "b",
"type": "int"
}
],
"current_state_name": "SS0",
"current_sub_state" : {
"type" : "Elem"
}
"name": "S0",
"type": "Automaton"
},
"name": "test",
"type": "Automaton"
}
}
Event is not recognized
Event is not executable
In this case, Event e1(0) is executed but e2(1) and e1("test") is not accepted.
20 Chapter 6. ExamplesSphinx with Markdown Documentation, Release 0.1.0
6.2.6 Execution on large specifications
Performance tests are located in the folder tests/perf. Let us consider the case tests/perf/
flow+kleene+autx100 generated from eASTD.
Fig. 1: Screenshot_from_2020-09-11_02-40-20
Run the following command
~# java -jar castd.jar -s tests/perf/flow+kleene+autx100/*.json -o tests/perf/
˓→flow+kleene+autx100/ -c
Then, execute the compiled program
~# cat events.txt
e1(1)
e2(2)
e3(3)
e1(1)
e2(2)
e3(3)
~# cat a.cpp
#include "Code.cpp"
#include "helper.h"
#define stringify(name) # name
enum KleeneState
{
KLEENE_NOTSTARTED,
KLEENE_STARTED
};
const char* kleeneState[] =
{
stringify(KLEENE_NOTSTARTED),
stringify(KLEENE_STARTED)
(continues on next page)
6.2. Run spec from command-line 21Sphinx with Markdown Documentation, Release 0.1.0
(continued from previous page)
};
enum AutState
{
S0,
S1
};
const char* autState[] =
{
stringify(S0),
stringify(S1)
};
struct TState_C_100
{
AutState autState;
};
struct TState_B_100
{
KleeneState kleeneState;
TState_C_100 ts_C_100;
};
struct TState_C_99
{
AutState autState;
...
~# ./a -i events.txt
22 Chapter 6. ExamplesCHAPTER
SEVEN
TECHNICAL DOCUMENTATION
The translation rules and the compilation approach are available here.
23Sphinx with Markdown Documentation, Release 0.1.0 24 Chapter 7. Technical documentation
CHAPTER
EIGHT
SLACK CHANNEL
Join project discussions here
25You can also read
