Initial release

1 files changed, 102 insertions, 0 deletions

diff --git a/QUICKSTART.md b/QUICKSTART.md
new file mode 100644
index 0000000..70509ec
--- /dev/null
+++ b/QUICKSTART.md
@@ -0,0 +1,102 @@
+# Quickstart guide {#quickstart}
+
+[TOC]
+
+# Dependencies
+
+## Building toolchain
+
+* `git`
+* `bash`
+* `find`
+* `make`
+* a c++ compiler that supports c++14 or c++17 (`g++` or `clang++`)
+* GNU `flex` (`lex` is untested)
+* GNU `bison` (`yacc` is untested)
+
+Optional:
+
+* `python3` for generating the sources using the module definitions
+* ...
+
+## External build dependencies
+
+* `systemc` (v2.3.3)
+
+## Documentation generation
+
+* `doxygen`
+* `dot` (via `graphviz` for example)
+
+## Traces visualization
+
+* GTKWave
+* `python3`
+* `python3-matplotlib`
+* ...
+
+# Building
+
+* First, make sure to install all the dependencies on your system, either locally or globally.
+* Then, fetch the code:
+
+      % git clone git@gitlab.inl90.ec-lyon.fr:czrounba/systemc-pcm-matrix-multiplication-simulator.git
+      % git submodule update --init --recursive
+
+* Copy `config.mk` to `config.local.mk` and update the compiler/library information there
+* If you installed systemc in a non-default path, you might need to update the
+`INCLUDES` and `LD_FLAGS` make variables in `config.mk`.
+* Finally, build `specs`
+      % make -j$(nproc)
+* Run a test circuits
+      % ./sim -t {waveguide,splitter,pcm,...}
+
+# Running
+
+Simulating a circuit from a netlist is straightforward:
+
+    % ./sim -f <my-circuit>.cir
+
+Look at the [cheatsheet](doc/resources/cheatsheet.pdf) for more information on the syntax to use.
+[](TODO: add a page for info on syntax of circuit files)
+
+After running, you can find results in the VCD tracefile (the file name can be specified in the circuit file with option `-o`).
+
+# Generating documentation (OUTDATED)
+
+First make sure `doxygen` and `graphviz` are installed, then:
+
+* To generate the doc, run:
+
+      % make doc
+
+* To open it in your default browser, run:
+
+      % make view-doc
+
+The generated documentation is available as HTML under `doc/html/` and compressed
+into a `tar.xz` archive under `doc/`. Other ouput formats are supported by `doxygen`.
+
+# Troubleshooting
+
+<!--
+If you cannot manage to build the simulator, you can check the `.gitlab-ci.yml`
+file which contains all the instructions to run to successfully build the code
+in a docker:
+
+* Install docker ([docker.io](https://docker.io)) and start it
+* Start an alpine container:
+
+      % docker run -it alpine:latest
+
+* Run all commands from the `before_script` section
+* Clone the git repo and update submodules:
+
+      % git clone <url> <local-folder>
+      % cd <local-folder>
+	  % git submodule update --init --recursive
+
+* Run all commands from the `build:script` section
+* Run all commands from the `test:script` section
+* Optional: Run all commands from the `doc:script` section
+-->