{"id":39434295,"url":"https://github.com/jgabaut/amboso","last_synced_at":"2026-01-28T12:22:52.640Z","repository":{"id":153009624,"uuid":"626802409","full_name":"jgabaut/amboso","owner":"jgabaut","description":"Build tool wrapping make. Written in bash.","archived":false,"fork":false,"pushed_at":"2026-01-17T13:48:22.000Z","size":1112,"stargazers_count":6,"open_issues_count":12,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-01-18T14:43:05.950Z","etag":null,"topics":["amboso","bash","bash-script","build-system","build-tool","builder","cli","make","makefile","shell","test-automation","testing-tools"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jgabaut.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-04-12T07:33:31.000Z","updated_at":"2025-12-17T21:04:00.000Z","dependencies_parsed_at":"2025-12-18T05:08:32.024Z","dependency_job_id":null,"html_url":"https://github.com/jgabaut/amboso","commit_stats":null,"previous_names":[],"tags_count":67,"template":false,"template_full_name":null,"purl":"pkg:github/jgabaut/amboso","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgabaut%2Famboso","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgabaut%2Famboso/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgabaut%2Famboso/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgabaut%2Famboso/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jgabaut","download_url":"https://codeload.github.com/jgabaut/amboso/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgabaut%2Famboso/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28845113,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-28T10:53:21.605Z","status":"ssl_error","status_checked_at":"2026-01-28T10:53:20.789Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["amboso","bash","bash-script","build-system","build-tool","builder","cli","make","makefile","shell","test-automation","testing-tools"],"created_at":"2026-01-18T04:10:12.379Z","updated_at":"2026-01-28T12:22:52.634Z","avatar_url":"https://github.com/jgabaut.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# amboso\n\n## A build tool wrapping make, with some git integration, powered by bash.\n\n## Table of Contents\n\n+ [What is this thing?](#witt)\n  + [Prerequisites](#prerequisites)\n+ [General Usage](#generalusage)\n  + [stego.lock](#stego)\n  + [Hard failure](#bin)\n  + [Tests directory](#kazoj)\n  + [Test mode](#test_mode)\n+ [Maintaining compatibility](#amboso_env)\n  + [For the super repo](#super_repo)\n  + [.gitignore for git mode](#gitignore_gitmode)\n  + [For the build process](#build_step)\n  + [About git mode](#git_mode)\n+ [Why should I consider using this?](#reasons)\n+ [Local installation](#local_install)\n+ [Legacy notes](#legacy_notes)\n  + [Legacy kazoj dir](#legacy_kazoj_lock)\n  + [Legacy version dirs](#legacy_version_dirs)\n  + [Legacy usage help script](#legacy_tryanvil)\n+ [Todo](#todo)\n\n### Note\n\nThis script has reached a size where I prefer moving development to a different language.\n\nAt the moment, a complementary implementation in Rust is being worked on [at this repo link](https://github.com/jgabaut/invil).\n\nHaving to rely on the Rust compiler is less flexible than a shell script, but the runtime alone can have such better results it's worth the move.\n\nSince version 1.8, a steady stream of patches have been included to ease the transition, with 2.0, to the Rust implementation as the reference one.\n\nNotably, version 1.9.x is highly unstable (in the sense that breaking changes have been made at patch level), and as such, should be considered deprecated once 2.0 is reached.\n\n## What is this thing? \u003ca name = \"witt\"\u003e\u003c/a\u003e\n\nThis tool is just a bash script handling some flags to perform automated builds (leveraging `make`, so there isn't much you can do \"only\" with this script) and tests.\n\nIf you want to run something like `git checkout vMY_TAG; make`, then you may need a few other args to move the completed build to an ordered directory tree.\n\n`amboso` uses a simple text file to pin some tags your repo offers, and enables your repo to handle a directory where you can keep all compiled version while keeping a clean `git status`.\n\nThe idea is nothing great.\n\nI wanted to build some older tagged version of a C project I was building using make, but for some of them I didn't have a proper past commit.\n\nI decided to try a little script to help me do this in the future, one command to prepare any tagged version I'd want, even tough I think this probably makes no sense to use over other build systems.\n\nStill, the added benefit of this little tool was worth the time for me.\n\nI did not want to learn how to write nice makefiles or chaining a couple git commands to checkout... Wait, you might still need to do that for this? Sigh...\n\n### I wanted to name a build tool `anvil`, while also making it sound like I'm  bozo for doing this poor `make` frontend.\n\n## Prerequisites \u003ca name = \"prerequisites\"\u003e\u003c/a\u003e\n\nTo install dependencies:\n\n- Ubuntu/Debian\n  ```console\n    apt install gawk bc\n  ```\n- macOS\n  ```console\n    brew install gawk bc\n  ```\n\n* At the moment the only supported build step command is `make rebuild`. This means you use make to run the target `rebuild`.\n  * Running with `-R` turns this back to the original behaviour, running just `make` with no target argument.\n\n* You need `bash`, I'm using version `5.1.x` but for now I think `\u003e=4.3` may work. More testing is needed.\n  * For macOS users: check this issue for unexpected behaviour on bash `3.x`. [#21](/../../issues/21)\n\n* You need `gawk` installed. While work to support `nawk` and `mawk` will be coming, it's not a priority as of now.\n  * macOS ships with `nawk` by default, but if you have `brew` installed, you should be able to run\n    `brew install gawk`\n\n* You should test you have `bc` installed, since it's used to calc runtimes.\n\n### Note\n\n  - If you include this repo as a submodule, you should also do the same and have the `anvil` link in your main repo directory, so you can call that instead of `REPO/amboso/amboso`.\n\n  - If you installed `anvil` globally with `sudo make install`, you should be mindful of different anvil versions if you are using this repo as a submodule.\n\n  - When running inside a dir containing an `amboso` folder, `anvil` will try to source `amboso_fn.sh` from `./amboso/amboso_fn.sh` instead of the file located inside global installation `/usr/local/bin/amboso_fn.sh`.\n  - You should see a warning message if a version mismatch occurs.\n\n## General usage \u003ca name = \"generalusage\"\u003e\u003c/a\u003e\n\n## stego.lock \u003ca name = \"stego\"\u003e\u003c/a\u003e\n\nThis file contains user-defined tags for supported versions and fundamental CLI arguments you don't want to type again.\n\nDefined env arguments are in this format:\n```\nenvvalue = \"val\"\n```\n\nDefined tags are in this format:\n```\n\"0.1.0\" = \"Desc\"\n```\n\nYou can define both git-mode tags and base-mode tags , each supported when running in the corresponding mode.\n\nDefinition of a base-mode tag **must** start with a `B`, like so\n```\n\"B0.0.1\" = \"1\"# A nice comment\n```\nThe `B` character will not be a part of your tag name, it only marks base-mode tags when at the start of a tag name.\n\n## Hard failure \u003ca name = \"bin\"\u003e\u003c/a\u003e\n\nI'll tell you that even the help option can fail, if you don't point this child to where your targets are and rely on naming your compliant folder `./bin/`.\nYou have a bin/ directory in the repo to test this behaviour.\nLocating folders is probably the only thing this script does, yet you still have to make sure to setup a proper amboso base directory with the targets dirs, and the `stego.lock` file.\n\nYou should rely on your `stego.lock` file to ensure you don't have to retype arguments you're 100% positive are correct, just to get the damn thing to build.\n\n### Note\n\nSince I've been using `/bin/` as a target dir myself, I haven't tested the script too much with the passing a different dirname with -D flag.\n\nI will look into this to ensure you don't have to stick to this name for the target directory.\n\n## bin/\n\nContains a directory for each supported tag (directories **must** start with an extra v prepended to the tag name, like so:\n\n```console\nsuper-repo\n├── amboso\n│   ├── amboso\n│   ├── bin\n│   │   ├── stego.lock\n│   │   ├── v0.1.0\n│   │   │   └── hello_world.c\n│   │   ├── v0.9.0\n│   │   │   ├── hello_world.c\n│   │   │   └── Makefile\n│   │   ├── v1.0.0\n│   │   └── v1.1.0\n│   │   └── v1.1.1\n│   ├── kazoj\n│   │   ├── bone\n│   │   │   └── good_test_exe\n│   │   └── kulpo\n│   │       └── bad_test_exe\n│   ├── CODEOWNERS\n│   ├── hello_world.c\n│   ├── LICENSE\n│   ├── Makefile\n│   └── README.md\n├── kazoj\n```\n\n```\nbin/vTAG_NAME/executable\n```\nie. directory bin contains a directory named \"vMYTAG\" for each supported version with name \"MYTAG\".\nIt also contains the stego.lock file.\n\nHaving to prepend every tag directory with 'v' may not be the best, but it's something we could change support for in the future.\n\nThe script **always** needs to know the directory containing the target builds, so **if you don't define one yourself** when running, by using -D :\n\n```sh\namboso -D SOME_DIR -h\n```\n\n, amboso will assume the target directory is in its current working directory and called 'bin', so `./bin`, and will try to read `stego.lock` to then try and gather all the values needed for -S -E -M flags.\n\n## kazoj/ \u003ca name = \"kazoj\"\u003e\u003c/a\u003e\n\nContains a directory for each test group, ATM there's one for successful tests and one for failures.\n\nThe two subdirectories can have any name and they can be specified in the `tests` section of `stego.lock`.\nCanonic names are, respectively:\n- `bone` : The general directory, for successful tests\n- `kulpo` : The error directory, for failure tests\n\nYou should have your own `kazoj` directory (which you can specify in `stego.lock`), in your super-repo.\n\n## Test mode \u003ca name = \"test_mode\"\u003e\u003c/a\u003e\n\nRunning `anvil` with `-t` or `-T` will start test mode.\n\n- If using `-t`, `anvil` will try to run ALL detected executable tests.\n- If using `-T`, `anvil` should only try to test the passed QUERY tag (must be a valid test name).\n\n- Use `-i` to record all the tests stdout and stderr to aptly named files.\n- You can do the same for just 1 file with `-b`.\n\n## Maintaining compatibility \u003ca name = \"amboso_env\"\u003e\u003c/a\u003e\n\nUsing amboso in a project requires some costraints to be valid both from the repo perspective **and** from the build process perspective.\n\n### For the super repo: \u003ca name = \"super_repo\"\u003e\u003c/a\u003e\n\nUse a `stego.lock` file to keep the main compliance checks stable.\n\nIt will store the source file name for single file mode and the target binary name.\n\nIt also stores the lowest version providing a Makefile, so that you can easily jump into a small project and not set up make right away (why not I guess).\nEven tought it only takes a couple minutes to do that, we like to postpone.\n\nSticking to a source file name and a target executable name should be pretty easy (maybe similar to repo name?).\n\nPlus, you can definitely change idea about those later, by always checking in your lock.\n\nI can't recommend using the -D flag everytime just to tell amboso where to look, but a fallback option to provide a different default directory name than `./bin` through the `stego.lock` itself could be added.\n\n### .gitignore for git mode  \u003ca name = \"gitignore_gitmode\"\u003e\u003c/a\u003e\n\nTo successfully use git mode, you must assure idempotency of the switch back to the main version. This is accomplished by correctly setting up your `.gitignore`, so that all object files \u0026 the executable are always ignored in all supported versions, and by always having the needed directory for any tag ready inside the tagged commit.\nThis must be done for the first version you want to support in git mode, and can stay pretty much untouched after.\nYour repo `.gitignore` should include some lines like this:\n\n```\n# ignore all object files\n*.o\n# also explicitly ignore our executable for good measure\nBIN-NAME\n# and also explicitly ignore our debug executable for good measure\nDEBUG-BIN-NAME\n# also ignore our builds dir\nBUILDS-DIR-NAME\n```\nWhere:\n  - BIN-NAME is the target executable\n  - DEBUG-BIN-NAME is its eventual debug compiled version\n  - BUILDS-DIR-NAME is the directory that you're expecting to use to store the built versions.\n    - If it's inside the repo, it's best to gnore it as a whole.\n    - If you're targeting `amboso \u003c2.0.4`, you must refer to the legacy handling of things, which included committing a new directory for every new amboso-supported tag... Link [here](#legacy_version_dirs).\n\nThat's it. You can easily\n\nI guess suggesting skipping object files and the main project executable is not a hot take.\n\n### For the build process: \u003ca name = \"build_step\"\u003e\u003c/a\u003e\n\nYou need to make sure all supported tags compile down to the same binary name (we'll see about this if/when we support other languages), and also that the eventual `make clean` correctly handles all the stuff not included in the tag itself.\nI don't think pegging the executable name is that restricting, as you could always use repo name. And maybe pretend symlinks are more than that to have a fancier name. :P\n\nEspecially for tags using a Makefile, you should make sure to actually output the compilation artifacts to the correct directory. Provided examples assume the output from compilation goes directly to repo root dir (where also your `./anvil` and `./bin` should ideally be).\nAnd I guess I must say that this script being mostly make frontend should tell you enough about the fact that you still need to create the Makefile for your project, if planning to use make as the build step tool. And here it is for another TODO add support for giving your own build/clean command. Coming soon tm\n\n## About git mode \u003ca name = \"git_mode\"\u003e\u003c/a\u003e\n\nAll files generated at runtime and not idempotently checked in will cause the `git switch -` to fail when trying to script the undoing of queried tag checkout.\nYou could script the removal of untracked files, but it only makes sense for the single file build, and you would still need to provide the full list of files to delete if you don't want to have bad surprises.\nI guess we could do `git clean -f -d` (also -d for the comfy dry run) but that risks too much, adding -i would make the cleaning interactive.\n\nTags supported by amboso running in git mode would be a subset of ` git tag -l `. This could mean supporting a non-compliant tag could be done with a full source build maintained inside the bin/v**VERS** directory. I don't know about that, if we're gonna front-end git tags better try to do it well.\n\n## Why would I use this when I can generate a Makefile automatically, or something? \u003ca name = \"reasons\"\u003e\u003c/a\u003e\n\nGood question, you shouldn't. No reason at all. Go back to your serious build system and leave these silly kid scripts to me.\n\n## Local installation \u003ca name = \"local_install\"\u003e\u003c/a\u003e\n\nRunning:\n\n```\nsudo make install\n```\n\ncopies `amboso_fn.sh` and `amboso` (renamed as `anvil`) to `/usr/local/bin`.\n\nThis allows calls to amboso plug into any directory, by having a default path.\n\nNot much useful by itself, since you won't probably have a compliant `stego.lock` in a random directory.\nMay be useful to me to anchor a default version locally.\n\nRun `sudo make uninstall` to clean the installed files.\n\n## Legacy notes \u003ca name = \"legacy_notes\"\u003e\u003c/a\u003e\n\nThis section contains notes about previous versions of `amboso`.\n\n### Legacy kazoj.lock usage, tests feature \u003ca name = \"legacy_kazoj_lock\"\u003e\u003c/a\u003e\n\n#### This info only applies to amboso \u003c= 2.0.0. After 2.0.0, there's no need for a kazoj.lock file, since the test directories name can be specified in stego.lock.\n\n`kazoj/` contains a directory for each test group, ATM there's one for successful tests and one for failures. The two subdirectories can have any name and they are to be specified in `kazoj.lock`. Canonic names are, respectively:\n- `bone` : The general directory, for successful tests\n- `kulpo` : The error directory, for failure tests\n\nYou should have your own `kazoj` directory (which you can specify in `stego.lock`), in your super-repo.\nAnd there, there should be a `kazoj.lock` file to remember the names of your cases/errors folders.\n\n### Legacy version directories \u003ca name = \"legacy_version_dirs\"\u003e\u003c/a\u003e\n\n#### This info only applies to amboso \u003c= 2.0.3. After 2.0.4, there's no need to prepare the build directory tree beforehand.\n\n**All** of your \"version\" directories (`vMYTAG/`) must include a `.gitignore` with some lines like this:\n\n```\n# You should put this .gitignore inside every one of your vMYTAG folders, each one before creating its own tagged commit on the repo:\n*\n!.gitignore\n#\n#The * line tells git to ignore all files in the folder, but !.gitignore tells git to still include the .gitignore file, thus keeping the directory checked in with your tag.\n```\n\n### Legacy usage help script \u003ca name = \"legacy_tryanvil\"\u003e\u003c/a\u003e\n\n#### This info only applies to amboso \u003c= 2.0.3. After 2.0.4, the tryanvil script is no longer working as expected, given that the whole bin dir creation is now done automatically when needed.\n\nTo see how this marvelous work of art works, run:\n\n```sh\n  cd utils/try-anvil\n  ./try_anvil\n```\nAll commands ran by the scripts will be shown on screen with a `+` before them.\n\n`try-anvil/try_anvil` It's a script running `./anvil` with various flags using the provided ./bin example references, so you can see how to call amboso with different flags.\n\n* The script symlinks `amboso` to `./anvil`, using `ln -s PATH_TO/amboso/amboso ./anvil`.\n\n* A revised version of the script may be added later.\n\n## Todo \u003ca name = \"todo\"\u003e\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjgabaut%2Famboso","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjgabaut%2Famboso","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjgabaut%2Famboso/lists"}