Update CONTRIBUTING.md

chaos-lang · Aug 16, 2020 · 1a774d6 · 1a774d6
1 parent c7707f7
commit 1a774d6
Show file tree

Hide file tree

Showing 2 changed files with 102 additions and 10 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -47,15 +47,28 @@ placing this command into a shell script like `dev.sh` and executing that, is th
    - http://catalog.compilertools.net/kits.html
    - https://www.ibm.com/support/knowledgecenter/en/ssw_aix_71/generalprogramming/ie_prog_4lex_yacc.html
 
-## Tips & Tricks
+## Frequently Asked Questions
 
-### How to debug a segmentation fault?
+### Could you please explain the directory structure of the project?
+
+ - `lexer/` contains the Lexical Analyzer (Tokenizer or Scanner in other words) definition
+which a Lex file named `lexer.l`
+ - `parser/` contains the grammar file for the parser which is a Yacc file named `parser.y`
+and several other functions related to parsing process.
+ - `ast/` contains the functions related to building an Abstract Syntax Tree (AST) from the program file that parsed.
+ - `interpreter/` contains the functions to register the Chaos modules and functions then
+execute the program using the Abstract Syntax Tree.
+ - `utilities/` contains the functions and macros used from everywhere in the project.
+ - `tests/` contains the example Chaos programs, outputs of those programs and some Bash scripts to execute those programs
+and then validate their output.
 
-Add `-ggdb` option to GCC like `gcc -o chaos chaos.tab.c lex.yy.c -ggdb` then:
+### How to debug a segmentation fault?
 
+You can use GNU Debugger to debug a segmentation fault. In order to do that,
+you need to simply compile the Chaos interpreter with `make dev` command which contains `-ggdb` option and then:
 
 ```
-mertyildiran@Corsair:~/Documents/chaos$ gdb
+$ gdb
 GNU gdb (Ubuntu 8.1-0ubuntu3.2) 8.1.0.20180409-git
 Copyright (C) 2018 Free Software Foundation, Inc.
 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
@@ -88,9 +101,83 @@ __strcmp_ssse3 () at ../sysdeps/x86_64/multiarch/../strcmp.S:173
 #1  0x0000555555555489 in isDefined (name=0x0) at symbol.h:145
 #2  0x0000555555554fd4 in addSymbol (name=0x0, type=INT, value=...) at symbol.h:33
 #3  0x00005555555556b7 in addSymbolInt (name=0x0, i=1) at symbol.h:203
-#4  0x00005555555564ae in yyparse () at chaos.y:121
-#5  0x00005555555569ea in main (argc=1, argv=0x7fffffffd798) at chaos.y:145
+#4  0x00005555555564ae in yyparse () at parser.y:121
+#5  0x00005555555569ea in main (argc=1, argv=0x7fffffffd798) at parser.y:145
 (gdb)
 ```
 
-**Note:** `make dev` contains `gcc -o chaos chaos.tab.c lex.yy.c -ggdb` so just run `make dev` instead.
+### Is there a debug mode?
+
+The Chaos interpreter has an option `-d` to enable the debug mode which tells you the details about
+the parsing and execution order using the Abstract Syntax Tree (AST):
+
+```
+$ chaos -d
+    Chaos Language 0.0.1-alpha (Aug 16 2020 21:18:05)
+    GCC version: 9.3.0 on linux
+    Turn chaos into magic!
+
+kaos> list a = [1, 2, 3]
+(Create)	ASTNode: {id: 1, node_type: AST_LIST_START, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 0}
+(Create)	ASTNode: {id: 2, node_type: AST_EXPRESSION_VALUE, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 0}
+(Create)	ASTNode: {id: 3, node_type: AST_VAR_CREATE_NUMBER, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 1}
+(Create)	ASTNode: {id: 4, node_type: AST_EXPRESSION_VALUE, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 0}
+(Create)	ASTNode: {id: 5, node_type: AST_VAR_CREATE_NUMBER, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 1}
+(Create)	ASTNode: {id: 6, node_type: AST_EXPRESSION_VALUE, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 0}
+(Create)	ASTNode: {id: 7, node_type: AST_VAR_CREATE_NUMBER, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 1}
+(Create)	ASTNode: {id: 8, node_type: AST_STEP, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 0}
+(Create)	ASTNode: {id: 9, node_type: AST_STEP, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 0}
+(Create)	ASTNode: {id: 10, node_type: AST_LIST_NESTED_FINISH, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 0}
+(Create)	ASTNode: {id: 11, node_type: AST_VAR_CREATE_LIST, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 1}
+(Register)	ASTNode: {id: 11, node_type: AST_VAR_CREATE_LIST, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 1}
+(Execute)	ASTNode: {id: 1, node_type: AST_LIST_START, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 0}
+(Execute)	ASTNode: {id: 6, node_type: AST_EXPRESSION_VALUE, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 0}
+(Execute)	ASTNode: {id: 7, node_type: AST_VAR_CREATE_NUMBER, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 1}
+(Execute)	ASTNode: {id: 4, node_type: AST_EXPRESSION_VALUE, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 0}
+(Execute)	ASTNode: {id: 5, node_type: AST_VAR_CREATE_NUMBER, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 1}
+(Execute)	ASTNode: {id: 8, node_type: AST_STEP, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 0}
+(Execute)	ASTNode: {id: 2, node_type: AST_EXPRESSION_VALUE, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 0}
+(Execute)	ASTNode: {id: 3, node_type: AST_VAR_CREATE_NUMBER, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 1}
+(Execute)	ASTNode: {id: 9, node_type: AST_STEP, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 0}
+(Execute)	ASTNode: {id: 10, node_type: AST_LIST_NESTED_FINISH, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 0}
+(Execute)	ASTNode: {id: 11, node_type: AST_VAR_CREATE_LIST, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 1}
+kaos> print "hello world"
+(Create)	ASTNode: {id: 12, node_type: AST_PRINT_STRING, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 0}
+(Register)	ASTNode: {id: 12, node_type: AST_PRINT_STRING, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 0}
+(Execute)	ASTNode: {id: 12, node_type: AST_PRINT_STRING, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 0}
+hello world
+kaos> exit
+(Create)	ASTNode: {id: 13, node_type: AST_EXIT_SUCCESS, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 0}
+(Register)	ASTNode: {id: 13, node_type: AST_EXIT_SUCCESS, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 0}
+(Execute)	ASTNode: {id: 13, node_type: AST_EXIT_SUCCESS, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 0}
+    You have chosen the order!
+(Free)	ASTNode: {id: 1, node_type: AST_LIST_START, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 0}
+(Free)	ASTNode: {id: 6, node_type: AST_EXPRESSION_VALUE, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 0}
+(Free)	ASTNode: {id: 7, node_type: AST_VAR_CREATE_NUMBER, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 1}
+(Free)	ASTNode: {id: 4, node_type: AST_EXPRESSION_VALUE, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 0}
+(Free)	ASTNode: {id: 5, node_type: AST_VAR_CREATE_NUMBER, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 1}
+(Free)	ASTNode: {id: 8, node_type: AST_STEP, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 0}
+(Free)	ASTNode: {id: 2, node_type: AST_EXPRESSION_VALUE, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 0}
+(Free)	ASTNode: {id: 3, node_type: AST_VAR_CREATE_NUMBER, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 1}
+(Free)	ASTNode: {id: 9, node_type: AST_STEP, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 0}
+(Free)	ASTNode: {id: 10, node_type: AST_LIST_NESTED_FINISH, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 0}
+(Free)	ASTNode: {id: 11, node_type: AST_VAR_CREATE_LIST, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 1}
+(Free)	ASTNode: {id: 12, node_type: AST_PRINT_STRING, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 0}
+(Free)	ASTNode: {id: 13, node_type: AST_EXIT_SUCCESS, module: /home/mertyildiran/Documents/chaos/__interactive__.kaos, string_size: 0}
+```
+
+Then search the AST node type (for example `AST_LIST_START`) in:
+
+ - `parser/parser.y` to determine the parser issues.
+ - `ast/ast.c` to analyze the Abstract Syntax Tree building issues.
+ - `interpreter/interpreter.c` to detect the issues related to execution of the program.
+
+### How am I suppose to use Clang sanitizers?
+
+Instead of compiling the Chaos interpreter using GCC (`make dev`), you can use Clang: `make clang-dev`
+
+We have also additional Makefile rules to use Clang sanitizers:
+
+ - MemorySanitizer: `make clang-dev-sanitizer-memory`
+ - AddressSanitizer: `make clang-dev-sanitizer-address`
+ - UndefinedBehaviorSanitizer: `make clang-dev-sanitizer-undefined_behavior`
diff --git a/README.md b/README.md
@@ -96,13 +96,14 @@ make install
 
 ```
 $ chaos
-    Chaos Language 0.0.1-alpha (Apr 10 2020 01:22:17)
-    GCC version: 7.4.0 on linux
+    Chaos Language 0.0.1-alpha (Aug 16 2020 21:56:00)
+    GCC version: 9.3.0 on linux
     Turn chaos into magic!
 
 kaos> print "hello world"
 hello world
-kaos>
+kaos> exit
+    You have chosen the order!
 ```
 
 ### Program File as Command-line Argument
@@ -135,3 +136,7 @@ make uninstall
 [**Bug Tracker**](https://github.com/chaos-lang/chaos/issues)
 
 [**Occultist Dependency Manager**](https://github.com/chaos-lang/occultist)
+
+[**Contribution Guide**](https://github.com/chaos-lang/chaos/blob/master/CONTRIBUTING.md)
+
+[**Code of Conduct**](https://github.com/chaos-lang/chaos/blob/master/CODE_OF_CONDUCT.md)