{"id":18302293,"url":"https://github.com/outscale/cognac","last_synced_at":"2025-04-09T10:10:57.322Z","repository":{"id":94912470,"uuid":"590828195","full_name":"outscale/COGNAC","owner":"outscale","description":"Give Headache, can be powerful ","archived":false,"fork":false,"pushed_at":"2024-12-31T12:26:44.000Z","size":528,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-02-15T04:24:03.976Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/outscale.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-19T10:02:51.000Z","updated_at":"2024-12-31T12:26:47.000Z","dependencies_parsed_at":"2024-03-08T17:29:16.821Z","dependency_job_id":"32b3b967-8440-441e-86ba-69515d021cee","html_url":"https://github.com/outscale/COGNAC","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/outscale%2FCOGNAC","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/outscale%2FCOGNAC/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/outscale%2FCOGNAC/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/outscale%2FCOGNAC/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/outscale","download_url":"https://codeload.github.com/outscale/COGNAC/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248018061,"owners_count":21034048,"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":[],"created_at":"2024-11-05T15:18:59.624Z","updated_at":"2025-04-09T10:10:57.298Z","avatar_url":"https://github.com/outscale.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Generator for Outscale API.\n[![Project Sandbox](https://docs.outscale.com/fr/userguide/_images/Project-Sandbox-yellow.svg)](https://docs.outscale.com/en/userguide/Open-Source-Projects.html)\n\n## Usage\n\n*note: The primary purpose of this repository is to generate source code. If your goal is to compile osc-sdk-c or oapi-cli, please refer to their respective repositories, which handle the code generation process for you.*\n\n### Brief\n\nTo configure the COGNAC Makefile, use `./configure.`\nYou can use `cognac_gen.sh SOURCE DEST LANGUAGE` to generate files from a template.\nThe Makefile is designed to help you generate all the required files.\nIf you want to generate everything, simply run `make`.\n\n### Generated Files\n\nCOGNAC generates four main files:\n- main.c: Source code for the CLI.\n- osc_sdk.h: Header file for the C library.\n- osc_sdk.c: Source code for the C library.\n- $(CLI_NAME)-completion.bash: Autocompletion file for the CLI.\n\n### cognac_gen.sh\n\ncognac_gen.sh is the script responsible for generating all the necessary files. It’s a shell script that calls sub-shell scripts and executes a few C binaries, which are compiled by the Makefile (see bin/).\n\nIt takes three arguments: a source file, a destination file, and a language.\nThe language argument is crucial as certain keywords might be interpreted differently depending on the target language.\n\nThe script uses a file called osc-api.json, which represents the OpenAPI specification in JSON format.\nFor the Outscale API, the YAML source is converted to JSON using `yq`: (https://kislyuk.github.io/yq/ or https://github.com/mikefarah/yq)\n\nWhen generating API calls, COGNAC by default assumes that the OpenAPI file contains components named CallRequest.\nFor example, if the API has a call named `CreatePony`, the corresponding component should be located at `#/components/schemas/CreatePonyRequest`.\n\nYou can modify the suffix of functions by using `--function-suffix=FUNCTION_SUFFIX` option with `./configure` command.\n\nAlternatively, you can generate functions based on the contents of `paths` by using the `./configure --from-path` option.\n\n*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`.*\n\n### Examples: Generating a CLI for a New API\n\n#### Configure Cognac for an API using elements in the schema as entry points for API calls.\n\nLet’s say you have an API that is not the Outscale API, and you want to generate a CLI for it.\nYou have a URL to a YAML file, such as `https://ponyapi.yolo/`, and the API request components are named `XInput` instead of `XRequest`.\n\nTo configure the Makefile to generate the CLI with the name `pony-cli`, and adjust the component naming convention, follow these steps:\n\nRun the following command:\n```bash\n./configure --cli-name=pony-cli --function-suffix Input --api-script='curl -s https://ponyapi.yolo | yq $(YQ_ARG)\" \u003e osc-api.json'\n```\n\n`-cli-name=pony-cli` set the generated binary name to `pony-cli`\n\n```bash\n--function-suffix Input\n```\n\nSearch for functions named XInput instead of XRequest.\n```bash\n--api-script='curl -s https://ponyapi.yolo | yq $(YQ_ARG) \u003e osc-api.json'\n```\n\n\nThis script is used to fetch the API file.\n\n\nHere’s what the script does:\n\n1. Retrieves the API in YAML format using curl -s `https://ponyapi.yolo/.`\n2. Converts the YAML to JSON using yq `$(YQ_ARG)`. *Note the usage of `$(YQ_ARG)`, so ./configure can handle go version of yq*\n\n\n#### Configure Cognac for an API using elements in the path as entry points for API calls.\n\nFor this example we will use [guru](https://apis.guru/api-doc/)\n\nRun the following command:\n```\n./configure --sdk-name=guru-sdk --cli-name=guru --from-path --api-script='curl -s https://api.apis.guru/v2/openapi.yaml | yq $(YQ_ARG)\" \u003e osc-api.json'\n```\n\n`--cli-name=guru`: Sets the generated binary name to `guru`.\n`--sdk-name=guru-sdk`: Sets the generated SDK name and the UserAgent to `guru-sdk`.\n`--from-path`: Generates API calls from elements in `paths` instead of `components.schemas`.\n\n\n#### Generate the Code\n\nOnce this setup is complete, you can now use the Makefile. It's also a good idea to run ./configure --help, as it contains several useful options.\n- `--wget-json-search`: Helps with downloading `json-search`, which can be tricky to install, **If unsure, we recommend using this by default**\n- `--compile-json-c`: Ensures a recent version of `json-c` is compiled, required for color support. **If unsure, we recommend using this by default**\n\nNow, simply run `make` to generate all necessary files and compile the CLI. This will also create a C SDK, consisting of two files: `osc-sdk.c` and `osc-sdk.h`.\n\nIf you want more control over the generation process, you can manually invoke specific Makefile rules:\n```bash\nmake main.c osc_sdk.c osc_sdk.h pony-cli-completion.bash pony-cli\n```\n\n\n## Dependencies\n\nHere’s a non-exhaustive list of required dependencies:\n- GNU sed\n- bash\n- jq\n- [json-search](https://github.com/cosmo-ray/json-search)\n- make\n- pkg-config\n- C Compiler\n\n### Optional Dependencies\n- libfuse2 (require if building appimage or with `--wget-json-search`)\n\n\n## Contribution\n\nOpen Pull Requests and Issues are welcome.\n\nIf you want to add binaries to the bin/ directory, please ensure they are easy to compile.\nThis means avoiding additional dependencies that are not already required by the CLI.\n\nFor more information about cognac code, see [HACKING.md](./HACKING.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foutscale%2Fcognac","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foutscale%2Fcognac","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foutscale%2Fcognac/lists"}