From: fennecdjay Date: Wed, 3 Jul 2019 14:01:59 +0000 (+0200) Subject: :book: Update docs X-Git-Tag: nightly~2381^2~9 X-Git-Url: http://10.10.0.4:5575/?a=commitdiff_plain;h=d3defe0d8d84856767c72eba08cf552241aa059c;p=gwion.git :book: Update docs --- diff --git a/docs/01_Overview/00_First_Steps/01_InstallingGwion.mdr b/docs/01_Overview/00_First_Steps/01_InstallingGwion.mdr new file mode 100644 index 00000000..06fc544e --- /dev/null +++ b/docs/01_Overview/00_First_Steps/01_InstallingGwion.mdr @@ -0,0 +1,39 @@ +# Installing gwion + +## Get the sources + +The source is accessible on [github](https://github.com). + +Provided you have git installed, you can get it with: + +``` sh +git clone https://github.com/fennecdjay/gwion +``` + +then change to the source directory +``` sh +cd gwion +``` + +### Don't forget submodules + +You'll need the sources for all base module +``` sh +git submodule update --init util ast +``` + +> At this point, you might want to configure the build. + In this case, have a look at the [configuration page](01_Overview/00_First_Steps/Configure.md) + + +## Build the libraries and program +``` sh +make +``` + +## Install the package + +``` sh +make install +``` +> You may need root privilege to do this. diff --git a/docs/01_Overview/BUILDING.mdr b/docs/01_Overview/BUILDING.mdr new file mode 100644 index 00000000..1babfe52 --- /dev/null +++ b/docs/01_Overview/BUILDING.mdr @@ -0,0 +1,38 @@ +# Build / Configure Gwion + +## Configure +### gwion-util + + * `USE_MEMCHECK`: compile with debug flags (`-g`) and enable asserts + * `USE_COVERAGE`: add coverage instrumentation + + +## Make +Basically, all that is left to do is +```sh +make +``` +The only environment variable affecting the operation is `PREFIX` + +Except `--(no-)double`, everything can be set when running make, +using environment variables. + +Drivers can be set on using, e.g. for *alsa* : `ALSA_D=1` or `ALSA_D=on`. +In the same way, then can be disabled with `ALSA_D=0` or `ALSA_D=off` + +### Running tests +```bash +make tests +``` +to run all tests, or +```bash +bash util/test.sh my_file_or_directory (.. other files/dirs ...) +``` +to run specific ones. +look [here](#testing.md) for more. +## Install +*maybe as root* +```sh +make install +``` +The only environment variable affecting the operation is `PREFIX` diff --git a/docs/01_Overview/Make.mdr b/docs/01_Overview/Make.mdr new file mode 100644 index 00000000..45a5452d --- /dev/null +++ b/docs/01_Overview/Make.mdr @@ -0,0 +1,7 @@ +# Makefile + +## Basic operations + +## translations + +## Docs diff --git a/docs/01_Overview/Testing.mdr b/docs/01_Overview/Testing.mdr new file mode 100644 index 00000000..3c3a79dd --- /dev/null +++ b/docs/01_Overview/Testing.mdr @@ -0,0 +1,28 @@ +# Tests +[test.sh](https://github.com/fennecdjay/Gwion/blob/dev/util/test.sh) +requires [valgrind](http://valgrind.org/) +there are two kinds of tests: + * [gwion](#gwion-tests) + * [bash](#bash-tests) + +## Gwion tests +those tests are just gwion (.gw) files, handling special comments: + * `// [skip]` (*optionally* followed by reason to skip) + * `// [todo]` (*optionally* followed by reason to delay testing) + * `// [contains]` followed by string to match + * `// [excludes]` followed by string not to match + +## Shell test +those tests are just bash (.sh) files. +they should start with this snippet +```bash +#!/bin/bash +# [test] #5 +n=0 +[ "$1" ] && n="$1" +[ "$n" -eq 0 ] && n=1 +source tests/sh/common.sh +``` + +## TODO + [ ] `bailout` system for early exit on failure diff --git a/docs/02_Reference/01_Functions/Lambdas.mdr b/docs/02_Reference/01_Functions/Lambdas.mdr new file mode 100644 index 00000000..132fbf32 --- /dev/null +++ b/docs/02_Reference/01_Functions/Lambdas.mdr @@ -0,0 +1,37 @@ +# Lambda + +## Overview + +Simply put, *lambda*s are anonymous functions. + +The syntax to create them is simple: +``` +\ variable0 variable1 ... { your code here } +``` +You can even use it to +### Call a function just once +@``` lambda_call0.gw +\ i { <<<"passed '", i, "'">>>; }(3); +@``` +@exec make -s CONTAINS="passed '3'" lambda_call0.test + + +## Use case + +### Passing to a function pointer +@``` lambda_fptr0.gw +typedef void fptr_t(int); +\ i { <<<"passed '", i, "'">>>; } @=> fptr_t fptr; +fptr(4); +@``` +@exec make -s CONTAINS="passed '4'" lambda_fptr0.test + +### As Argument to Functions +@``` lambda_args0.gw +typedef void fptr_t(int); +fun void test(fptr_t fptr) { + fptr(5); +} +test(\ i { <<<"passed '", i, "'">>>; }); +@``` +@exec make -s CONTAINS="passed '5'" lambda_args0.test diff --git a/docs/02_Reference/01_Functions/Variadic.mdr b/docs/02_Reference/01_Functions/Variadic.mdr new file mode 100644 index 00000000..23a75196 --- /dev/null +++ b/docs/02_Reference/01_Functions/Variadic.mdr @@ -0,0 +1,18 @@ +# Variadic functions + +> A function whoses arity is not fixed. + +Well, a function that takes a fixed number of arguments, and additionnal ones. + +## a simple example +@``` variadic.gw +fun void variadic_test(int i, ...) { + <<< "first argument is ", i >>>; + vararg.start; + <<< "\tadditionnal argument", vararg.i >>>; + vararg.end; +} +variadic_test(1); +variadic_test(1, 2); +variadic_test(1, 2, 3); +@``` diff --git a/docs/02_Reference/01_Functions/function.mdr b/docs/02_Reference/01_Functions/function.mdr new file mode 100644 index 00000000..f92a174f --- /dev/null +++ b/docs/02_Reference/01_Functions/function.mdr @@ -0,0 +1,19 @@ +# Functions + +## a simple (commented example) + +@``` function0.gw +// declare function 'test_function' +// with return type int +// taking an int as argument +fun int test_function(int arg) { + // return the argument + 2 + return arg + 2; +} + +// now call the function (and debug print the result) +<<>>; +// or use alternate syntax +<<<1 => test_function>>>; +@``` +@exec make -s function0.test diff --git a/docs/02_Reference/ControlFlow/ControlFlow.mdr b/docs/02_Reference/ControlFlow/ControlFlow.mdr new file mode 100644 index 00000000..2e9c1854 --- /dev/null +++ b/docs/02_Reference/ControlFlow/ControlFlow.mdr @@ -0,0 +1,4 @@ +# Control Flow + +## Repeats +let start simple ;-) diff --git a/docs/02_Reference/ControlFlow/Loops.mdr b/docs/02_Reference/ControlFlow/Loops.mdr new file mode 100644 index 00000000..4b787b4b --- /dev/null +++ b/docs/02_Reference/ControlFlow/Loops.mdr @@ -0,0 +1 @@ +# Loops diff --git a/docs/02_Reference/ControlFlow/Repeat.mdr b/docs/02_Reference/ControlFlow/Repeat.mdr new file mode 100644 index 00000000..bbfea851 --- /dev/null +++ b/docs/02_Reference/ControlFlow/Repeat.mdr @@ -0,0 +1,21 @@ +# the Repeat keyword +let start simple ;-) +The easiest way to do an action repeatidly in Gwion is, ... the **repeat** keyword! + +## Very basic example +@``` repeat.gw +repeat(3) + <<<"Hello, world!">>>; +@``` +@exec make -s CONTAINS="Hello" repeat.test + +## Block example +of course this also works with a block code. + +@``` repeat2.gw +repeat(3) { + maybe ? "You" : "Me" => string s; + <<<"Hello, ", s, "!">>>; +} +@``` +@exec make -s CONTAINS="Hello" repeat2.test diff --git a/docs/02_Reference/ControlFlow/forloop.mdr b/docs/02_Reference/ControlFlow/forloop.mdr new file mode 100644 index 00000000..5d01609f --- /dev/null +++ b/docs/02_Reference/ControlFlow/forloop.mdr @@ -0,0 +1,63 @@ +# For Loops +**For** loops in Gwion is pretty similar to classic **C** syntax + +## basic loops +@``` forloop0.gw +for(int i; i < 3; ++i) + <<>>; +@``` +@exec make -s forloop0.test + +Of course, it also works with a block of code. + +@``` forloop2.gw +for(int i; i < 3; ++i) { + i/2 => float f1; + i/2. => float f2; + <<>>; +} +@``` +@exec make -s forloop2.test + +## Nested Loops +@``` forloop3.gw +int array[3][4]; + +for(int i; i < 3; ++i) { + for(int j; j < 4; ++j) { + <<>>; + } +} +@``` +@exec make -s forloop3.test + +### Auto Loops + +#### Simple auto loop +@``` forloop4.gw +int array[2][3]; +for(auto a: array) { + <<>>; + for(auto b: a) + <<>>; +} +@``` +@exec make -s forloop4.test + +### Auto Pointer loop +With the simple auto loop, you only get the value in the array. +If you want to change it, you need a pointer + +@``` forloop5.gw +int array[2][3]; +int i; +for(auto a: array) { + for(auto @b: a) + <<<++i => *b>>>; +} +for(auto a: array) { + for(auto @b: a) + <<<*b>>>; +} +@``` +@exec make -s forloop5.test diff --git a/docs/02_Reference/ControlFlow/whileuntil.mdr b/docs/02_Reference/ControlFlow/whileuntil.mdr new file mode 100644 index 00000000..798b0334 --- /dev/null +++ b/docs/02_Reference/ControlFlow/whileuntil.mdr @@ -0,0 +1,23 @@ +# Loops + +@``` while0.gw +while(true) { + if(maybe) + break; + <<<"running...">>>; +} +@``` +@exec make -s while0.test + +well this may output nothing... +lets try + +@``` while1.gw +<<>>; +do{ + if(maybe) + break; + <<<"running...">>>; +} while(true); +@``` +@exec make -s while1.test diff --git a/docs/02_Reference/Extending/WIP_Driver.mdr b/docs/02_Reference/Extending/WIP_Driver.mdr new file mode 100644 index 00000000..20478632 --- /dev/null +++ b/docs/02_Reference/Extending/WIP_Driver.mdr @@ -0,0 +1,9 @@ +# Giving gwion a new driver + +## basics + +> in order to use GWION_CTL ... + +# concept + +# upd driver diff --git a/docs/02_Reference/Extending/WIP_Plugins.mdr b/docs/02_Reference/Extending/WIP_Plugins.mdr new file mode 100644 index 00000000..cd1822fd --- /dev/null +++ b/docs/02_Reference/Extending/WIP_Plugins.mdr @@ -0,0 +1,68 @@ +# Writing a Gwion plugin + +> THIS IS OUTDATED. please look at the source code in src/lib/ instead + + * [getting started] + +## Getting started +use the script + +### headers +``` +#include "vm.h" +#include "instr.h" +#include "import.h +``` + + +### Class +Define the type: +``` +struct Type_ t_mytype = { "MyType", SZ_INT, &t_object}; +``` +> every type extending t_object should have SZ_INT + +### Handling Constructors and Destructors +#### CTOR +``` +CTOR(mytype_ctor) { + /* constructor code here */ +} +``` +#### DTOR +``` +DTOR(mytype_dtor) { + /* destructor code here */ +} +``` + +those macros provide two variables: + * `o`: the *M_Object* for the (con/des)tructor + * `shred`: the *VM_Shred* for the (con/des)tructor + +``` +CHECK_BB(import_class_begin(env, &t_mytpe, env->global_nspc, mytype_ctor, mytype_dtor)) +``` +#### variable +declare a `m_int`. coding convention require + * a leading *_o* + * a following *_type_* +```c +m_int o_mytype_myvaroffset; +``` +#### function +```c +/* declare a member function */ +MFUN(mytype_memberfunction) { + /* code here */ +} + +SFUN(mtype_staticfunction) { + /* code here */ +} +``` + +#### operator + +### Import function + diff --git a/docs/02_Reference/Preprocessor.mdr b/docs/02_Reference/Preprocessor.mdr new file mode 100644 index 00000000..e4e9d832 --- /dev/null +++ b/docs/02_Reference/Preprocessor.mdr @@ -0,0 +1 @@ +# Gwion Preprocessor diff --git a/docs/09_Benchmarks.mdr b/docs/09_Benchmarks.mdr new file mode 100644 index 00000000..0f81e941 --- /dev/null +++ b/docs/09_Benchmarks.mdr @@ -0,0 +1,86 @@ +# Benchmarks + +We'll need a bash script + + + +### and a gnuplot script + + + +## Show the results +Then just run it +@exec bash benchmark.sh; #rm bench.plot benchmark.sh diff --git a/docs/10_BuildindTheDocs.mdr b/docs/10_BuildindTheDocs.mdr new file mode 100644 index 00000000..99190c1c --- /dev/null +++ b/docs/10_BuildindTheDocs.mdr @@ -0,0 +1,7 @@ +# How this doc is build + +## mdr + +## makefile + +## mkdocs diff --git a/docs/assets/benchmark/binary-trees.dat b/docs/assets/benchmark/binary-trees.dat index 2d13d935..6b1f8faa 100644 --- a/docs/assets/benchmark/binary-trees.dat +++ b/docs/assets/benchmark/binary-trees.dat @@ -1,3 +1,3 @@ -gwion 0.188183 0.30 -wren 0.237885 0.33 -lua 0.32730 2.38 +gwion 0.186408 0.33 +wren 0.230839 0.18 +lua 0.304600 0.24 diff --git a/docs/assets/benchmark/binary-trees.png b/docs/assets/benchmark/binary-trees.png index 8bf59bca..fb261d56 100644 Binary files a/docs/assets/benchmark/binary-trees.png and b/docs/assets/benchmark/binary-trees.png differ diff --git a/docs/assets/benchmark/fib-recurs.dat b/docs/assets/benchmark/fib-recurs.dat index ad47b5da..0e5f0c83 100644 --- a/docs/assets/benchmark/fib-recurs.dat +++ b/docs/assets/benchmark/fib-recurs.dat @@ -1,3 +1,3 @@ -gwion 5.4589 0.43 -wren 13.4301 0.40 -lua 7.2227 0.22 +gwion 5.3602 0.76 +wren 13.7710 0.54 +lua 7.5633 0.92 diff --git a/docs/assets/benchmark/fib-recurs.png b/docs/assets/benchmark/fib-recurs.png index a0637217..837be4b0 100644 Binary files a/docs/assets/benchmark/fib-recurs.png and b/docs/assets/benchmark/fib-recurs.png differ diff --git a/docs/assets/benchmark/fib.dat b/docs/assets/benchmark/fib.dat index 5f73c7cd..7c079271 100644 --- a/docs/assets/benchmark/fib.dat +++ b/docs/assets/benchmark/fib.dat @@ -1,3 +1,3 @@ -gwion 0.086354 0.61 -wren 0.21780 0.55 -lua 0.219805 0.43 +gwion 0.085051 0.65 +wren 0.212702 0.17 +lua 0.21245 0.69 diff --git a/docs/assets/benchmark/fib.png b/docs/assets/benchmark/fib.png index 8bbc056b..899201fd 100644 Binary files a/docs/assets/benchmark/fib.png and b/docs/assets/benchmark/fib.png differ diff --git a/docs/assets/benchmark/method-call.dat b/docs/assets/benchmark/method-call.dat index 083d19cb..539c489e 100644 --- a/docs/assets/benchmark/method-call.dat +++ b/docs/assets/benchmark/method-call.dat @@ -1,3 +1,3 @@ -gwion 0.091682 0.31 -wren 0.107952 0.40 -lua 0.25460 1.10 +gwion 0.095307 0.31 +wren 0.111192 0.41 +lua 0.26047 1.04 diff --git a/docs/assets/benchmark/method-call.png b/docs/assets/benchmark/method-call.png index d23c6ad5..ce6a9734 100644 Binary files a/docs/assets/benchmark/method-call.png and b/docs/assets/benchmark/method-call.png differ