|
|
@@ -0,0 +1,91 @@
|
|
|
+Installation
|
|
|
+============
|
|
|
+
|
|
|
+Installing the Modelverse is unnecessary, as it is mere Python code and doesn't use installation scripts.
|
|
|
+All scripts which are generally useful are found in the 'scripts' directory, and are written in OS-independent Python code.
|
|
|
+
|
|
|
+There will be two things that you need to do only once:
|
|
|
+
|
|
|
+ 1. Make copies of test files, by executing `scripts/fix_files.py`
|
|
|
+ 2. Generate a bootstrap file, by executing `scripts/generate_bootstrap.py`
|
|
|
+
|
|
|
+That is it!
|
|
|
+You will only have to recreate a bootstrap file if you modify any of the code in the bootstrap folder, which is likely not a good idea unless you know what you are doing!.
|
|
|
+
|
|
|
+Starting up the Modelverse
|
|
|
+==========================
|
|
|
+
|
|
|
+Starting up the Modelverse is easy: simply execute the `scripts/run_local_modelverse.py` script, with as parameter the port you want to use.
|
|
|
+This will compile the Modelverse statechart and execute it afterwards.
|
|
|
+You can now directly communicate with the Modelverse user initialisation layer.
|
|
|
+It is not recommended that you do this manually, so we will now introduce the action language.
|
|
|
+
|
|
|
+Compiling Action Language
|
|
|
+=========================
|
|
|
+
|
|
|
+For a more user-friendly experience, an Action Language compiler was introduced that can automatically generate Modelverse instructions.
|
|
|
+During compilation, a live Modelverse is required, as the bytecodes are immediately uploaded after compilation.
|
|
|
+The Modelverse uses a traditional compilation phase and linking phase, though this is all hidden to the user through the `scripts/make_all.py` script.
|
|
|
+The script takes as parameter the address of the Modelverse, the username in whose name to execute the code, and a list of source files.
|
|
|
+For realistic applications, we recommend to always link to the bootstrap code, by including the file `bootstrap/\*.alc`.
|
|
|
+Even on systems that don't support globbing (e.g., Windows), this will automatically be expanded by the compiler.
|
|
|
+
|
|
|
+For example, to compile the simple textual interface, you must compile the interface's action language, together with all bootstrapping code (the libraries):
|
|
|
+
|
|
|
+```sh
|
|
|
+python scripts/make_all.py http://localhost:8001 test_user bootstrap/*.alc integration/code/pn_interface.alc
|
|
|
+```
|
|
|
+
|
|
|
+Compilation is (relatively) smart, as it will not compile code again that is already present in the Modelverse.
|
|
|
+As such, except for the first user, the bootstrap code no longer needs to be compiled, only linked.
|
|
|
+In the future, this is expected to become more user friendly for users, such that they no longer need to have the bootstrapping code available locally.
|
|
|
+
|
|
|
+After this part, your action language in `integration/code/pn_interface.alc` is compiled and running on the Modelverse.
|
|
|
+The Modelverse will, during loading, execute the main function it finds in any of these files.
|
|
|
+
|
|
|
+Communicating with the Modelverse
|
|
|
+=================================
|
|
|
+
|
|
|
+Now that your code is running on the Modelverse, you will want to communicate with it!
|
|
|
+To do this, you can use whatever tool you want, as long as it can send and receive XML/HTTPRequests.
|
|
|
+For example, a mere internet browser can already communicate with the Modelverse, though not in the most user-friendly way.
|
|
|
+
|
|
|
+A nicer way is through the Python prompt script `scripts/prompt.py`.
|
|
|
+It will ask you the location of the Modelverse, and the user to connect to.
|
|
|
+After that, it will print out all the output of the Modelverse, and send in all your queries directly to the Modelverse.
|
|
|
+
|
|
|
+Performance
|
|
|
+===========
|
|
|
+
|
|
|
+Performance of the Modelverse is currently rather low, especially in the make\_all script, as this uses an explicitly modelled bytecode upload system.
|
|
|
+To drastically increase performance, this can be switched to a native implementation and a different compiler.
|
|
|
+Additionally, all compilations of source files can happen in parallel, using as many cores as are available.
|
|
|
+Even further, you can skip symbol resolution in the linking phase if you know that all symbols are defined.
|
|
|
+To do all of this, use the `scripts/make_parallel.py` script.
|
|
|
+It is identical to the `scripts/make_all.py` script, but uses multiple cores and uses native code.
|
|
|
+
|
|
|
+Tests
|
|
|
+=====
|
|
|
+
|
|
|
+Running the tests is easy: simply execute `scripts/run_tests.py` in the main modelverse folder.
|
|
|
+This will invoke the necessary build commands (to create bootstrapping code etc.) and call the tests for each individual aspect of the Modelverse.
|
|
|
+Note that testing is done using py.test, which is the only dependency of the Modelverse (and only for tests, of course).
|
|
|
+
|
|
|
+Regarding performance of tests, the tests will try to execute the compilation in parallel, though they test both the explicitly modelled upload system and the native code.
|
|
|
+As such, test performance for the "co\_\*" tests is known to be slow.
|
|
|
+
|
|
|
+Using PyPy
|
|
|
+----------
|
|
|
+
|
|
|
+Since all scripts chain the invocation with the same interpreter as originally invoking the script, you will need to install py.test for PyPy.
|
|
|
+Assuming that you already have PyPy installed, you can simply install py.test using these commands:
|
|
|
+```sh
|
|
|
+wget https://bootstrap.pypa.io/get-pip.py
|
|
|
+pypy get-pip.py --user
|
|
|
+pypy -m pip install pytest --user
|
|
|
+```
|
|
|
+
|
|
|
+From then on, you can simply invoke all tests in PyPy using:
|
|
|
+```sh
|
|
|
+pypy scripts/run_tests.py
|
|
|
+```
|
