--- /dev/null
+# 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.
--- /dev/null
+# 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`
--- /dev/null
+# Makefile
+
+## Basic operations
+
+## translations
+
+## Docs
--- /dev/null
+# 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
--- /dev/null
+# 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
--- /dev/null
+# 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);
+@```
--- /dev/null
+# 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)
+<<<test_function(0)>>>;
+// or use alternate syntax
+<<<1 => test_function>>>;
+@```
+@exec make -s function0.test
--- /dev/null
+# Control Flow
+
+## Repeats
+let start simple ;-)
--- /dev/null
+# 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
--- /dev/null
+# For Loops
+**For** loops in Gwion is pretty similar to classic **C** syntax
+
+## basic loops
+@``` forloop0.gw
+for(int i; i < 3; ++i)
+ <<<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;
+ <<<i, " " , f1, " ", 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) {
+ <<<array[i][j]>>>;
+ }
+}
+@```
+@exec make -s forloop3.test
+
+### Auto Loops
+
+#### Simple auto loop
+@``` forloop4.gw
+int array[2][3];
+for(auto a: array) {
+ <<<a>>>;
+ for(auto b: a)
+ <<<b>>>;
+}
+@```
+@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
--- /dev/null
+# Loops
+
+@``` while0.gw
+while(true) {
+ if(maybe)
+ break;
+ <<<"running...">>>;
+}
+@```
+@exec make -s while0.test
+
+well this may output nothing...
+lets try
+
+@``` while1.gw
+<<<maybe>>>;
+do{
+ if(maybe)
+ break;
+ <<<"running...">>>;
+} while(true);
+@```
+@exec make -s while1.test
--- /dev/null
+# Giving gwion a new driver
+
+## basics
+
+> in order to use GWION_CTL ...
+
+# concept
+
+# upd driver
--- /dev/null
+# 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
+```
+<!-- TODO: verify this -->
+
+### 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
+
--- /dev/null
+# Gwion Preprocessor
--- /dev/null
+# Benchmarks
+
+We'll need a bash script
+
+<link rel=styleSheet href="../assets/doc.css" TYPE="text/css"><div id="org-categories"><ul class="lev1"><li><a href="#">Show the code</a></li><ul class="lev2"><a href="#">
+@``` benchmark.sh
+#!/bin/sh
+language=("gwion" "wren" "lua")
+extension=("gw" "wren" "lua")
+test_dir="tests/benchmark"
+plot_script="bench.plot"
+: "${repeats:=10}"
+
+run() {
+ perf stat -r"$repeats" "$1" "$test_dir/$3.$2" 2>&1 | grep "time elapsed" |
+ sed 's/ *\([0-9]*\),\([0-9]*\) .* seconds time elapsed *( +- *\([0-9]*\),\([0-9]*\)% )/\1.\2 \3.\4/'
+}
+
+get_list() {
+ for file in $test_dir/*.gw
+ do basename "$file" .gw
+ done
+}
+
+get_test() {
+ for (( i=0; i<=$(( ${#language[@]} -1 )); i++ ))
+ do echo "${language[$i]} $(run "${language[$i]}" "${extension[$i]}" "$1")"
+ done > "docs/assets/benchmark/$1.dat"
+}
+
+plot() {
+ gnuplot -e "bench='$1'" "$plot_script"
+}
+
+for bench in $(get_list)
+do
+echo $bench
+ get_test "$bench"
+ plot "$bench"
+ echo "### $bench"
+ echo '<link rel=styleSheet href="../assets/doc.css" TYPE="text/css"><div id="org-categories"><ul class="lev1"><li><a href="#">Show the code</a></li><ul class="lev2"><a href="#">'
+ echo "\`\`\`"
+ cat "$test_dir/$bench.gw"
+ echo "\`\`\`"
+ echo '</a></a></li></ul></ul></div>'
+ echo ""
+done
+@```
+</a></a></li></ul></ul></div>
+
+### and a gnuplot script
+
+<link rel=styleSheet href="../assets/doc.css" TYPE="text/css"><div id="org-categories"><ul class="lev1"><li><a href="#">Show the code</a></li><ul class="lev2"><a href="#">
+@``` bench.plot
+set terminal png truecolor
+
+#if (!exists("bench"))
+# bench = 'bench'
+if (!exists("test_dir"))
+ test_dir = 'tests/benchmark'
+
+dat_name = sprintf("docs/assets/benchmark/%s.dat", bench)
+
+stats dat_name using 0:2 noout
+max = STATS_max_y+(0.1*STATS_max_y)
+
+set title bench
+set output sprintf("docs/assets/benchmark/%s.png", bench)
+set xrange [-0.5:((ceil(STATS_max_x))+0.5)]
+set yrange [0:max]
+set boxwidth 0.50
+set nokey
+set xtics nomirror
+set ytics nomirror
+
+set style fill transparent solid 0.25 # partial transparency
+set style fill noborder # no separate top/bottom lines
+
+plot dat_name using 0:2:($2*($3/100.0)):xtic(2) with boxerrorbar lc "blue" notitle, \
+ '' using 0:(max-(0.05*max)):1 with labels
+@```
+</a></a></li></ul></ul></div>
+
+## Show the results
+Then just run it
+@exec bash benchmark.sh; #rm bench.plot benchmark.sh
--- /dev/null
+# How this doc is build
+
+## mdr
+
+## makefile
+
+## mkdocs
-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
-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
-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
-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
projects / gwion.git / commitdiff
