{"id":22034268,"url":"https://github.com/jc-ll/crokus","last_synced_at":"2025-05-07T15:06:11.989Z","repository":{"id":65611294,"uuid":"175449181","full_name":"JC-LL/crokus","owner":"JC-LL","description":"C parser written in Ruby, for experimental purpose","archived":false,"fork":false,"pushed_at":"2022-05-09T16:33:20.000Z","size":1545,"stargazers_count":15,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-07T15:06:10.904Z","etag":null,"topics":["ast","c","cfg","control-flow-graph","experimental","parser"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JC-LL.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-03-13T15:31:18.000Z","updated_at":"2025-04-22T18:21:58.000Z","dependencies_parsed_at":"2023-01-31T17:31:46.039Z","dependency_job_id":null,"html_url":"https://github.com/JC-LL/crokus","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JC-LL%2Fcrokus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JC-LL%2Fcrokus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JC-LL%2Fcrokus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JC-LL%2Fcrokus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JC-LL","download_url":"https://codeload.github.com/JC-LL/crokus/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252902614,"owners_count":21822261,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ast","c","cfg","control-flow-graph","experimental","parser"],"created_at":"2024-11-30T09:07:36.073Z","updated_at":"2025-05-07T15:06:11.976Z","avatar_url":"https://github.com/JC-LL.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# crokus\nCrokus is a simple C compiler front-end written in Ruby, for experimental purpose.\nToday it does not produce assembly per se.\n\nCrokus parses a fair subset of C, using outrageous tricks : many test examples are provided in the tests directory.\nMake your own opinion whether Crokus is helpful for you or not (drop me an email !).\n\nCrokus generates an AST (abstract syntax tree), that can be visualized using Graphviz.\nCrokus also generates a control-flow graph of each function in the C code.\nThis CFG can also be viewed using Graphviz, and then viewed in your favorite image format (png, svg etc).\n\nCrokus also generates an intermediate format (IR).\n\nHere is an example of such AST (f2.c)\n![AST](/doc/f2_ast.png)\n\nThen, its Control-Flow Graph and its textual IR. We are close to assembly !\n![AST](/doc/f2_code_cfg_ir.png)\n\nIf you want to implement a transformation, have a look at the Visitor class, for instance used in the PrettyPrinter class.\n\nHere how it looks : simply type\n\n ```bash\n   \u003e crokus\n   Crokus (0.1.5)- (c) JC Le Lann 2016-20\n   Usage: crokus [options]\n      -h, --help                       Show help message\n      -p, --parse                      parse only\n          --pp                         pretty print back source code\n          --ast                        abstract syntax tree (AST)\n          --cfg                        control-flow graphs for each function\n          --tac                        draw three address code (TAC) CFG\n          --emit-ir                    dump textual IR from TAC CFG\n          --random PARAMS              generates random c files, using parameters\n          --trojan FUNC                insert Syracuse Trojan in function FUNC\n          --vv                         verbose\n      -v, --version                    Show version number\n   need a C file : crokus [options] \u003cfile.c\u003e\n   ```\nLet's compile a C file named \"f2.c\" :\n  ```bash\n  \u003e crokus f2.c\n  Crokus (0.1.5)- (c) JC Le Lann 2016-20\n  [+] parsing f2.c\n  [+] building CFGs\n   |--[+] visitFunction 'f2'\n       |--[+] graphviz file saved as 'cfg_f2.dot'\n       |--[+] cleaning cfg 'f2'\n       |--[+] optimizing cfg 'f2'\n       |--[+] cfg size for 'f2' : 11\n       |--[+] graphviz file saved as 'cfg_f2_clean.dot'\n   |--[+] visitFunction 'main'\n       |--[+] graphviz file saved as 'cfg_main.dot'\n       |--[+] cleaning cfg 'main'\n       |--[+] optimizing cfg 'main'\n       |--[+] cfg size for 'main' : 1\n       |--[+] graphviz file saved as 'cfg_main_clean.dot'\n  [+] pretty_print\n   |--[+] saved as f2_pp.c\n  [+] building TAC\n   |--[+] tac builder for 'f2'\n       |--[+] graphviz file saved as 'cfg_tac_f2_clean.dot'\n   |--[+] tac builder for 'main'\n       |--[+] graphviz file saved as 'cfg_tac_main_clean.dot'\n  [+] emit textual IR\n   |--[+] IR for 'f2'\n       |--[+] generated f2.ir\n   |--[+] IR for 'main'\n       |--[+] generated main.ir\n  ```\n\n## generating random c\n\nCrokus allows to generate random c functions, for experimental purposes. To run, type :\n\n  ```bash\n  crokus --random params.yaml\n  ```\nThe **yaml** files (one is given in tests directory) provides a set of parameters for the random generation, like this (without the '-' in the yaml file ):\n  ```yaml\n  name : \"test1\"\n  nb_inputs: 2\n  nb_outputs: 2\n  nb_basic_blocks: 50\n  nb_int_vars: 10\n  nb_int_arrays: 4\n  avg_size_int_arrays: 10\n  avg_assigns_per_bbs: 2\n  avg_assigns_expression_depth: 2\n  avg_forloop_iterations: 10\n  accept_while_loops: false\n  ```\nHere an exemple of one generated code (content is omitted here but actually present in the basic blocks):\n\u003c!-- ![AST](/doc/generated_50.png | width=100) --\u003e\n\u003cimg src=\"/doc/generated_50.png\" alt=\"AST\" width=\"500\" height=\"500\"\u003e\n\n## Trojan insertion\nCrokus is also malicious. It is able to insert a specific Trojan (named Syracuse) on a specfic C function. Then the execution may slow down mysteriously. The triggering of Syracuse depends on the combination of specific input values (need documentation).\nSyracuse is inserted such that other C compilers cannot remove it through plain dataflow analysis: Syracuse is not _dead code_.\n\n## How to install :\n- rely on RubyGems (worldwide repository of Ruby libraries) : \"gem install crokus\"\n\n## How to use :\n- [x] on the command line, type \"crokus -h\". A simple help is provided. Not many options !\n- [x] crokus --ast test.c will generate the complete AST for this C file.\n- [x] crokus --cfg test.c will generate a CFG for each function enclosed in the C file.\n- [x] crokus test.c will try to generate a three-address code (TAC) textual representation (work in progress !)\nMore to come ! Stay tuned !\n\n## How to help :\n- report bugs by email or using github. I will try to do my best to fix them.\n- suggest or provide enhancements (Ruby code)\n- suggest or provide transformations on AST or CFG\n- Anyone interested in SSA form ? Help wanted !\n- generate code for specific purposes.\n\n## Contact :\n  - I am opened to any sort of collaboration !\n  - Drop me an email at : jean-christophe.le_lann@ensta-bretagne.fr or jc.lelann@gmail.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjc-ll%2Fcrokus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjc-ll%2Fcrokus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjc-ll%2Fcrokus/lists"}