From a68744dffa846140596fd315492b54a257d31625 Mon Sep 17 00:00:00 2001 From: Matthias Gatto Date: Mon, 16 Dec 2024 10:55:10 +0100 Subject: [PATCH] improve doc Signed-off-by: Matthias Gatto --- HACKING.md | 29 +++++++++++++++++++++++++++++ README.md | 2 ++ 2 files changed, 31 insertions(+) diff --git a/HACKING.md b/HACKING.md index b0a36fd..ab4f762 100644 --- a/HACKING.md +++ b/HACKING.md @@ -2,6 +2,13 @@ *Essential Information for Hacking COGNAC* +## Enabling debug + +To enable debug, use `--debug-mode` in `./configure` + +then the `debug` commande in the shell script will print some information. +without this option debug will print nothing + ## Unix Philosophy and COGNAC Paradigms. Most people have heard the phrase "Do One Thing and Do It Well" and associate it with the Unix philosophy. It’s said that this is how Unix operates and how it should be. @@ -35,6 +42,28 @@ A relatively easy way to add a feature in Cognac is to start by modifying the ge For exemple, if you modify a function like `parse_thatarg()` in "osc_sdk.c", once the changes are working, you can then search (using a tool like grep) through the generator code to find where `parse_thatarg` is generated. From there, you can add modifications to the generator to make the change permanent and automated. +## Example to add a new API, that doesn't work at first. + +Let's say you ahve configure cognac like this + +```sh + ./configure --sdk-name=myapi-sdk --cli-name=guru --api-script='cat myapi-api.json > osc-api.json' --debug-mode --from-path +``` + +doing that you will use try to generate the api from path, with debug enable. + +now let's say you have this output while calling `make`: +``` +____complex_struct_func_parser____ +nothing found____cli_parser____ +nothing founderror in jsonnothing founderror in jsonnothing founderror in jsonnothing founderror in jsonnothing founderror in jsonnothing founderror in jsonnothing founderror in json./cognac_gen.sh lib.h osc_sdk.h c +debug mode is on +``` + +This mean that durring `____complex_struct_func_parser____` `____cli_parser____`, the scripts fails to pasre some part of osc-api json. +To debug it, you should look at what happen durring `____complex_struct_func_parser____` and `____cli_parser____` inside `cognac_gen.sh` + + ## helpers.sh Most functions in helper.sh are documented, so read through it if you want to understand some of the most commonly used functions in cognac_gen. diff --git a/README.md b/README.md index 929819b..a55bdb5 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,8 @@ For example, if the API has a call named `CreatePony`, the corresponding compone You can change the suffix of functions using `./configure --function-suffix FUNCTION_SUFFIX` +Or you can generate functions using what is inside `paths`, using `./configure --from-path` + *Note: There are two versions of yq: one written in Python and one in Go. The default version depends on your distribution. On Arch-based distributions, the Python version is typically the default, whereas on Debian-based distributions, the Go version is default. COGNAC supports both, but to use the Go version, you need to pass `--yq-go` to `./configure`.* ### Example: Generating a CLI for a New API