Big update (#11)

* done a lot of details and mainly zig and c interop

* added comptime to index

* added TODO why python so slow and changed the way I do a loop

* last time i do a commit this big

* small details

* fixed what was asked

* fixed small details

* fixed details to green threads after hpc course

.gitignore

@@ -0,0 +1 @@
+docs/WIP

docs/allocators.org

@@ -14,7 +14,9 @@ This part is documented thanks to various resources:
 - The Zig's standard library code
 
 ** General pattern
-In Zig for library development, a good practice is to pass an allocator as a parameter, so the programmer can choose the best allocator for his use case.
+TODO selon le prof il faudrait "prouver" ou "sourcer" cette affirmation comme quoi cest une good practice mais je ne sais pas trop quoi dire:
+
+"In Zig for library development, a good practice is to pass an allocator as a parameter, so the programmer can choose the best allocator for his use case."
 
 In the Zig standard library, this pattern is used a lot.
 
@@ -102,7 +104,7 @@ Moreover, there is also a thread-safe fixed buffer allocator for thread-safety u
 
 ** Arena allocator
 The arena allocator takes a child allocator as input. This pattern is used to allocate multiple pieces of memory and free them at once.
-There is no need in the arena allocator to free memory manually, it's the function ~deinit~ that is responsible for freeing all to allocated memory.
+There is no need in the arena allocator to free memory manually, it's the function ~deinit~ that is responsible for freeing *all* the allocated memory by this allocator.
 
 The Zig documentation recommends this pattern when an application runs from start to end without a cyclic pattern.
 For example: command line application.
@@ -184,6 +186,8 @@ The ~deinit~ function of the arena allocator will free all the buffers by iterat
 A general purpose allocator is available in Zig, this is a safe allocator that can prevent double free memory, "use after free" and detect memory leaks.
 The general purpose allocator is safety first design, but it's still faster than the page allocator ([[https://zig.guide/standard-library/allocators/][Zig guide allocator]])
 
+Note that it aims to be even faster in the [[https://github.com/ziglang/zig/issues/12484][future]].
+
 The general purpose allocator is a function that takes as argument a comptime configuration struct and return a type.
 (this code snippet comes from the standard library [[https://github.com/ziglang/zig/blob/0.11.x/lib/std/heap/general_purpose_allocator.zig][general_purpose_allocator.zig]])
 #+begin_src zig
@@ -349,6 +353,11 @@ The ~C~ standard allocator can also be used, this allocator has high performance
 However, to use this allocator, the ~libC~ is required.
 Adding the ~libC~ in the project will add more dependencies.
 
-
 ** TODO How to use Zig to detect memory leaks
 *** TODO Comparison between gcc-utils sanitizer, Valgrind, and Zig memory leak detection
+
+** TODO ?
+TODO talk about how malloc and calloc work in C with the on demand memory allocation (page fault each time with need more memory) is there a similar system in zig ? can we choose to have on demand memory or can we all allocate at once ?
+
+** Conclusion
+TODO selon le prof cest bien de faire une conclusion et introduction sur la plupart des concepts abordés

docs/build-system.org

@@ -2,11 +2,25 @@
 #+cite_export: csl ieee.csl
 
 * Compilation - build system
+
+#+INCLUDE: "./zig-package-manager.org" :minlevel 2
+
 ** TODO Comptime
 
 ** TODO How to use the build system
 
-** TODO Build modes
+** Build modes
+Zig build modes are way easier for beginners to graps compared to [[https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html][C]]
+
+There are only 4 different build modes:
+- Debug (default)
+- ReleaseFast
+- ReleaseSafe
+- ReleaseSmall
+
+You can check them in more details [[https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html][here]]
+
+There are also a few other options you can tweak like avx [[https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html][here]]
 
 *** TODO Build steps
 https://zig.guide/build-system/build-steps

docs/case-studies.org

@@ -0,0 +1,8 @@
+* Case studies
+** Interacting with processuses
+TODO
+https://github.com/Pismice/rename-i3-workspace
+Was zig the good choice ?
+Was it easy ?
+What were the problems ?
+What libraries did i use ?

docs/code-styles.org

@@ -0,0 +1,70 @@
+#+bibliography: bibliography.bib
+
+** Code styles
+*** Style guide
+**** fmt
+First it is important to know that Zig comes with a formatter that you can use using:
+#+begin_src shell
+zig fmt file.zig
+#+end_src
+This util is going to enforce basic things for you like:
+- Indentation
+- Braces alignment
+- Line length
+- ....
+**** Naming conventions
+1. =TitleCaseTypeName=: for types and structs that are callable (for "classes" in other languages basically)
+2. =camelCaseFunctionName=: for functions
+3. =snake\_case\_variable_name=: for variables and everything else
+
+*** undefined and null values
+TODO for some reason the 2 org block code are not working, maybe i should "testsuite"
+TODO how can i make the second one print the error ?
+
+In Zig you can leave variables uninitialized, but you have to do that explicitly contrary to C where you can leave variables uninitialized and never truly notice it. Note that leaving the value undefined is going to leave the memory of this variable to some complete nonsense value (except in Debug mode where it will be [[https://github.com/ziglang/zig/issues/15603
+][set to 0xaa]])
+#+begin_src zig :imports '(std) :main 'yes :testsuite 'no
+const my_var: u8 = undefined;
+std.debug.print("my_var: {}\n", .{my_var});
+#+end_src
+
+This is to be avoided as much as possible, if you have some in your code it might makes sense to use an Optional type instead so that compiler can scream at you :)
+#+begin_src zig :imports '(std) :main 'yes :testsuite 'no
+const my_var: ?u8 = null;
+
+// .? is syntaxic sugar for "orelse unreachable" which is going
+// unreachable is going to emit a panic (unable to unwrapp null) !
+// THIS CODE WILL PANIC IF UNCOMMENTED
+// _ = my_var.?;
+
+// if value is "null" then "42" will be assigned
+const value: u8 = my_var orelse 42;
+
+// print 42 because value was null before
+std.debug.print("my_var = {}\n", .{value});
+#+end_src
+
+#+RESULTS:
+
+*** Zen
+Zig encourages you to use the [[https://ziglang.org/documentation/0.12.0/#Zen][Zen philosophy]], they reflect well the spirit behind Zig, here they are:
+- Communicate intent precisely.
+- Edge cases matter.
+- Favor reading code over writing code.
+- Only one obvious way to do things.
+- Runtime crashes are better than bugs.
+- Compile errors are better than runtime crashes.
+- Incremental improvements.
+- Avoid local maximums.
+- Reduce the amount one must remember.
+- Focus on code rather than style.
+- Resource allocation may fail; resource deallocation must succeed.
+- Memory is a resource.
+- Together we serve the users.
+
+Sources:
+https://ziglang.org/documentation/master/#Type-Coercion-undefined
+https://nathancraddock.com/blog/zig-naming-conventions/o
+https://ziglang.org/documentation/master/#undefined
+https://ziglang.org/documentation/master/#Style-Guide
+https://github.com/ziglang/zig/blob/master/lib/std/fmt.zig

docs/compiler-messages.org

@@ -0,0 +1,26 @@
+** Compiler messages
+In a language that aims to report most of its issues at compilation time, it is important to have clear and concise error messages. However at the time we are writing this it is sadly not the case. Here are a few compiler messages that you might encounter that are very hard to understand:
+
+*** Trying to print without the correct struct syntax
+We are going to start with the most basic one, everyone doing Zig did at least one time
+#+begin_src zig :imports '(std) :main 'yes :testsuite 'no
+std.debug.print("Hello I am {} years old", 12);
+#+end_src
+
+#+begin_example
+/home/tetratrux/.zvm/0.11.0/lib/std/fmt.zig:87:9: error: expected tuple or struct argument, found comptime_int
+        @compileError("expected tuple or struct argument, found " ++ @typeName(ArgsType));
+#+end_example
+
+Is the type of error you should get, from reading that we cant even know from where the problem is in our code, no line number, no stacktrace, nothing.
+
+But if you read the message carefully and you know that [[https://ziglang.org/documentation/master/std/#std.debug.print][print]] second argument except a struct with the *.{}* syntax, you realize that you passed a value with the wrong type.
+
+So when you get that type of error message make sure that you are printing your message correctly with the second argument that should be a struct with the *.{}* syntax.
+
+#+begin_src zig :imports '(std) :main 'yes :testsuite 'no
+std.debug.print("Hello I am {} years old", .{12});
+#+end_src
+
+This is an [[https://github.com/ziglang/zig/issues/19158][ongoing issue]] by the time I am writing this in 0.12.0
+