<!--
=====================================
generator=datazen
version=3.1.4
hash=a4fbd061471e04dda4fbf58664532b82
=====================================
-->
# yambs ([3.0.4](https://pypi.org/project/yambs/))
[](https://pypi.org/project/yambs/)
[](https://codecov.io/github/vkottler/yambs)
*Yet another meta build-system.*
## Documentation
### Generated
* By [sphinx-apidoc](https://vkottler.github.io/python/sphinx/yambs)
(What's [`sphinx-apidoc`](https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html)?)
* By [pydoc](https://vkottler.github.io/python/pydoc/yambs.html)
(What's [`pydoc`](https://docs.python.org/3/library/pydoc.html)?)
## Python Version Support
This package is tested with the following Python minor versions:
* [`python3.12`](https://docs.python.org/3.12/)
## Platform Support
This package is tested on the following platforms:
* `ubuntu-latest`
* `macos-latest`
* `windows-latest`
# Introduction
It's undeniable that a software engineer must implement some project-workflow
tooling as a coming-of-age endeavor.
Your current workflow is slow and cumbersome? Time to roll up your sleeves and
improve it!
What does every build system on the block advertise? *Speed* of course!
What else do they advertise? Scalability! Compile source repositories that only
fleets of data centers can even fathom checking out entire source trees of.
Compile your whole company's software stack in only eight hours! (Down from
ten from the previous build-system we used!!!)
**Most build systems optimize for technical problem solving, and leave
user-facing configuration and recurring-interaction mechanisms an
afterthought.**
Want to use our awesome tool that solves every hard computer-science problem
known to mankind? Sorry but you need to learn a totally bespoke programming
language to get started. What's that? Does it have linting + formatting +
static-analysis tooling? Your text editor doesn't even ship with syntax
highlighting out of the box? C'mon just configure your build. Buy some books
on Amazon and spend a few days reading the manual cover-to-cover.
This project aims at bringing sanity to the user-facing parts of build systems:
**the commands you enter, and the coherence of configuration data that actually
warrants human management** (and not automated generation).
## Prior Art
* [vmklib](https://github.com/vkottler/vmklib) - a "Makefile library" with a
Python extensibility interface, great for generic project workflow tasks, but
not specific enough for meta build-system purposes
* [datazen](https://github.com/vkottler/datazen) - a solution for connecting
the awesomeness of [Jinja](https://jinja.palletsprojects.com/en/3.1.x/) to
data and template directories, eliminating a need for writing bespoke code
to generate common boilerplate when a bit of configuration data is sufficient
* [rcmpy](https://github.com/vkottler/rcmpy) - a more targeted `datazen`,
focused on a "put templates and configuration data here" approach to
generating userspace configuration files (for e.g. your developer workstation
editor, shell and other configurations)
* [userfs](https://github.com/vkottler/userfs) - a tool for performing
arbitrary fresh-system bootstrapping tasks (cloning repositories, building
and installing software from source) at the userspace level, rather than as
a privileged user
# Y.A.W.R
`yambs` ain't wheel reinvention.
This isn't a build-system alternative - it generates build instructions for
[ninja](https://ninja-build.org/).
What's that? Have I heard of [CMake](https://cmake.org/)?
[Meson](https://mesonbuild.com/) perhaps? What about
[Bazel](https://bazel.build/)? GNU's [Make](https://www.gnu.org/software/make/)
is a timeless classic.
## Build System Cardinal Sins
### Infinite Configurability and Flexibility
It's understandable that almost every build system implementation begins with
the objective of compiling sources and linking programs from an *existing*
source tree, with probably a lot of inconsistent organization conventions.
This drives complexity into the build system's interface for being told what
to do. **It's rare for any build system to have an out-of-the-box notion of
where to look for things and what work to do.**
### Infinite Scalability
Isn't any modern piece of software junk if it can't scale to millions of
concurrent network connections / disk read-write tasks / computations?
That's what the current software engineering zeitgeist will tell you. Why
define conventions for small/medium projects, trivial to spawn the N+1'th
instance when the need arises, when you can spend all of your time making an
infinitely scalable build system for every line of code that thousands of
people are contributing every day?
## Solutions
1. Sane out-of-the-box conventions: put your code here (and organize it by
following a specific convention), put your configuration data here.
# Command-line Options
```
$ ./venv3.12/bin/mbs -h
usage: mbs [-h] [--version] [-v] [-q] [--curses] [--no-uvloop] [-C DIR]
{compile_config,dist,download,gen,native,uf2conv,noop} ...
Yet another meta build-system.
options:
-h, --help show this help message and exit
--version show program's version number and exit
-v, --verbose set to increase logging verbosity
-q, --quiet set to reduce output
--curses whether or not to use curses.wrapper when starting
--no-uvloop whether or not to disable uvloop as event loop driver
-C DIR, --dir DIR execute from a specific directory
commands:
{compile_config,dist,download,gen,native,uf2conv,noop}
set of available commands
compile_config load configuration data and write results to a file
dist create a source distribution
download download GitHub release assets
gen poll the source tree and generate any new build files
native generate build files for native-only target projects
uf2conv convert to UF2 or flash directly
noop command stub (does nothing)
```
## Sub-command Options
### `compile_config`
```
$ ./venv3.12/bin/mbs compile_config -h
usage: mbs compile_config [-h] [-i INCLUDES_KEY] [-u] [-e]
output inputs [inputs ...]
positional arguments:
output file to write
inputs files to read
options:
-h, --help show this help message and exit
-i INCLUDES_KEY, --includes-key INCLUDES_KEY
top-level key to use for included files (default:
includes)
-u, --update whether or not to use the 'update' merge strategy
(instead of 'recursive')
-e, --expect-overwrite
allow configuration files to overwrite data when
loaded
```
### `dist`
```
$ ./venv3.12/bin/mbs dist -h
usage: mbs dist [-h] [-c CONFIG] [-s]
options:
-h, --help show this help message and exit
-c CONFIG, --config CONFIG
the path to the top-level configuration file (default:
'yambs.yaml')
-s, --sources set this flag to only capture source files
```
### `download`
```
$ ./venv3.12/bin/mbs download -h
usage: mbs download [-h] [-o OWNER] [-r REPO] [-O OUTPUT] [-p PATTERN]
options:
-h, --help show this help message and exit
-o OWNER, --owner OWNER
repository owner (default: 'vkottler')
-r REPO, --repo REPO repository name (default: 'toolchains')
-O OUTPUT, --output OUTPUT
output directory (default: '.')
-p PATTERN, --pattern PATTERN
a pattern to use to select project specifications
filtered by name
```
### `gen`
```
$ ./venv3.12/bin/mbs gen -h
usage: mbs gen [-h] [-c CONFIG] [-i] [-w] [-s] [-n]
options:
-h, --help show this help message and exit
-c CONFIG, --config CONFIG
the path to the top-level configuration file (default:
'yambs.yaml')
-i, --single-pass only run a single watch iteration
-w, --watch whether or not to continue watching for source tree
changes
-s, --sources whether or not to only re-generate source manifests
-n, --no-build whether or not to skip running 'ninja'
```
### `native`
```
$ ./venv3.12/bin/mbs native -h
usage: mbs native [-h] [-c CONFIG] [-i] [-w] [-s] [-n]
options:
-h, --help show this help message and exit
-c CONFIG, --config CONFIG
the path to the top-level configuration file (default:
'yambs.yaml')
-i, --single-pass only run a single watch iteration
-w, --watch whether or not to continue watching for source tree
changes
-s, --sources whether or not to only re-generate source manifests
-n, --no-build whether or not to skip running 'ninja'
```
### `uf2conv`
```
$ ./venv3.12/bin/mbs uf2conv -h
usage: mbs uf2conv [-h] [-b BASE] [-f FAMILY] [-o FILE] [-d DEVICE_PATH] [-l]
[-c] [-D] [-w] [-C] [-i]
[INPUT]
positional arguments:
INPUT input file (HEX, BIN or UF2)
options:
-h, --help show this help message and exit
-b BASE, --base BASE set base address of application for BIN format
(default: 0x2000)
-f FAMILY, --family FAMILY
specify familyID - number or name (default: 0x0)
-o FILE, --output FILE
write output to named file; defaults to "flash.uf2" or
"flash.bin" where sensible
-d DEVICE_PATH, --device DEVICE_PATH
select a device path to flash
-l, --list list connected devices
-c, --convert do not flash, just convert
-D, --deploy just flash, do not convert
-w, --wait wait for device to flash
-C, --carray convert binary file to a C array, not UF2
-i, --info display header information from UF2, do not convert
```
# Internal Dependency Graph
A coarse view of the internal structure and scale of
`yambs`'s source.
Generated using [pydeps](https://github.com/thebjorn/pydeps) (via
`mk python-deps`).
Raw data
{
"_id": null,
"home_page": "https://github.com/vkottler/yambs",
"name": "yambs",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": "Vaughn Kottler <vaughnkottler@gmail.com>",
"keywords": null,
"author": "Vaughn Kottler",
"author_email": "Vaughn Kottler <vaughnkottler@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/fe/d4/be4e9e03cd2ec0f66fa202fa22d0a20722f4c14d88a43c95f0f71a16e030/yambs-3.0.4.tar.gz",
"platform": null,
"description": "<!--\n =====================================\n generator=datazen\n version=3.1.4\n hash=a4fbd061471e04dda4fbf58664532b82\n =====================================\n-->\n\n# yambs ([3.0.4](https://pypi.org/project/yambs/))\n\n[](https://pypi.org/project/yambs/)\n\n[](https://codecov.io/github/vkottler/yambs)\n\n\n\n*Yet another meta build-system.*\n\n## Documentation\n\n### Generated\n\n* By [sphinx-apidoc](https://vkottler.github.io/python/sphinx/yambs)\n(What's [`sphinx-apidoc`](https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html)?)\n* By [pydoc](https://vkottler.github.io/python/pydoc/yambs.html)\n(What's [`pydoc`](https://docs.python.org/3/library/pydoc.html)?)\n\n## Python Version Support\n\nThis package is tested with the following Python minor versions:\n\n* [`python3.12`](https://docs.python.org/3.12/)\n\n## Platform Support\n\nThis package is tested on the following platforms:\n\n* `ubuntu-latest`\n* `macos-latest`\n* `windows-latest`\n\n# Introduction\n\nIt's undeniable that a software engineer must implement some project-workflow\ntooling as a coming-of-age endeavor.\n\nYour current workflow is slow and cumbersome? Time to roll up your sleeves and\nimprove it!\n\nWhat does every build system on the block advertise? *Speed* of course!\n\nWhat else do they advertise? Scalability! Compile source repositories that only\nfleets of data centers can even fathom checking out entire source trees of.\nCompile your whole company's software stack in only eight hours! (Down from\nten from the previous build-system we used!!!)\n\n**Most build systems optimize for technical problem solving, and leave\nuser-facing configuration and recurring-interaction mechanisms an\nafterthought.**\n\nWant to use our awesome tool that solves every hard computer-science problem\nknown to mankind? Sorry but you need to learn a totally bespoke programming\nlanguage to get started. What's that? Does it have linting + formatting +\nstatic-analysis tooling? Your text editor doesn't even ship with syntax\nhighlighting out of the box? C'mon just configure your build. Buy some books\non Amazon and spend a few days reading the manual cover-to-cover.\n\nThis project aims at bringing sanity to the user-facing parts of build systems:\n**the commands you enter, and the coherence of configuration data that actually\nwarrants human management** (and not automated generation).\n\n## Prior Art\n\n* [vmklib](https://github.com/vkottler/vmklib) - a \"Makefile library\" with a\nPython extensibility interface, great for generic project workflow tasks, but\nnot specific enough for meta build-system purposes\n* [datazen](https://github.com/vkottler/datazen) - a solution for connecting\nthe awesomeness of [Jinja](https://jinja.palletsprojects.com/en/3.1.x/) to\ndata and template directories, eliminating a need for writing bespoke code\nto generate common boilerplate when a bit of configuration data is sufficient\n* [rcmpy](https://github.com/vkottler/rcmpy) - a more targeted `datazen`,\nfocused on a \"put templates and configuration data here\" approach to\ngenerating userspace configuration files (for e.g. your developer workstation\neditor, shell and other configurations)\n* [userfs](https://github.com/vkottler/userfs) - a tool for performing\narbitrary fresh-system bootstrapping tasks (cloning repositories, building\nand installing software from source) at the userspace level, rather than as\na privileged user\n\n# Y.A.W.R\n\n`yambs` ain't wheel reinvention.\n\nThis isn't a build-system alternative - it generates build instructions for\n[ninja](https://ninja-build.org/).\n\nWhat's that? Have I heard of [CMake](https://cmake.org/)?\n[Meson](https://mesonbuild.com/) perhaps? What about\n[Bazel](https://bazel.build/)? GNU's [Make](https://www.gnu.org/software/make/)\nis a timeless classic.\n\n## Build System Cardinal Sins\n\n### Infinite Configurability and Flexibility\n\nIt's understandable that almost every build system implementation begins with\nthe objective of compiling sources and linking programs from an *existing*\nsource tree, with probably a lot of inconsistent organization conventions.\n\nThis drives complexity into the build system's interface for being told what\nto do. **It's rare for any build system to have an out-of-the-box notion of\nwhere to look for things and what work to do.**\n\n### Infinite Scalability\n\nIsn't any modern piece of software junk if it can't scale to millions of\nconcurrent network connections / disk read-write tasks / computations?\n\nThat's what the current software engineering zeitgeist will tell you. Why\ndefine conventions for small/medium projects, trivial to spawn the N+1'th\ninstance when the need arises, when you can spend all of your time making an\ninfinitely scalable build system for every line of code that thousands of\npeople are contributing every day?\n\n## Solutions\n\n1. Sane out-of-the-box conventions: put your code here (and organize it by\nfollowing a specific convention), put your configuration data here.\n\n# Command-line Options\n\n```\n$ ./venv3.12/bin/mbs -h\n\nusage: mbs [-h] [--version] [-v] [-q] [--curses] [--no-uvloop] [-C DIR]\n {compile_config,dist,download,gen,native,uf2conv,noop} ...\n\nYet another meta build-system.\n\noptions:\n -h, --help show this help message and exit\n --version show program's version number and exit\n -v, --verbose set to increase logging verbosity\n -q, --quiet set to reduce output\n --curses whether or not to use curses.wrapper when starting\n --no-uvloop whether or not to disable uvloop as event loop driver\n -C DIR, --dir DIR execute from a specific directory\n\ncommands:\n {compile_config,dist,download,gen,native,uf2conv,noop}\n set of available commands\n compile_config load configuration data and write results to a file\n dist create a source distribution\n download download GitHub release assets\n gen poll the source tree and generate any new build files\n native generate build files for native-only target projects\n uf2conv convert to UF2 or flash directly\n noop command stub (does nothing)\n\n```\n\n## Sub-command Options\n\n### `compile_config`\n\n```\n$ ./venv3.12/bin/mbs compile_config -h\n\nusage: mbs compile_config [-h] [-i INCLUDES_KEY] [-u] [-e]\n output inputs [inputs ...]\n\npositional arguments:\n output file to write\n inputs files to read\n\noptions:\n -h, --help show this help message and exit\n -i INCLUDES_KEY, --includes-key INCLUDES_KEY\n top-level key to use for included files (default:\n includes)\n -u, --update whether or not to use the 'update' merge strategy\n (instead of 'recursive')\n -e, --expect-overwrite\n allow configuration files to overwrite data when\n loaded\n\n```\n\n### `dist`\n\n```\n$ ./venv3.12/bin/mbs dist -h\n\nusage: mbs dist [-h] [-c CONFIG] [-s]\n\noptions:\n -h, --help show this help message and exit\n -c CONFIG, --config CONFIG\n the path to the top-level configuration file (default:\n 'yambs.yaml')\n -s, --sources set this flag to only capture source files\n\n```\n\n### `download`\n\n```\n$ ./venv3.12/bin/mbs download -h\n\nusage: mbs download [-h] [-o OWNER] [-r REPO] [-O OUTPUT] [-p PATTERN]\n\noptions:\n -h, --help show this help message and exit\n -o OWNER, --owner OWNER\n repository owner (default: 'vkottler')\n -r REPO, --repo REPO repository name (default: 'toolchains')\n -O OUTPUT, --output OUTPUT\n output directory (default: '.')\n -p PATTERN, --pattern PATTERN\n a pattern to use to select project specifications\n filtered by name\n\n```\n\n### `gen`\n\n```\n$ ./venv3.12/bin/mbs gen -h\n\nusage: mbs gen [-h] [-c CONFIG] [-i] [-w] [-s] [-n]\n\noptions:\n -h, --help show this help message and exit\n -c CONFIG, --config CONFIG\n the path to the top-level configuration file (default:\n 'yambs.yaml')\n -i, --single-pass only run a single watch iteration\n -w, --watch whether or not to continue watching for source tree\n changes\n -s, --sources whether or not to only re-generate source manifests\n -n, --no-build whether or not to skip running 'ninja'\n\n```\n\n### `native`\n\n```\n$ ./venv3.12/bin/mbs native -h\n\nusage: mbs native [-h] [-c CONFIG] [-i] [-w] [-s] [-n]\n\noptions:\n -h, --help show this help message and exit\n -c CONFIG, --config CONFIG\n the path to the top-level configuration file (default:\n 'yambs.yaml')\n -i, --single-pass only run a single watch iteration\n -w, --watch whether or not to continue watching for source tree\n changes\n -s, --sources whether or not to only re-generate source manifests\n -n, --no-build whether or not to skip running 'ninja'\n\n```\n\n### `uf2conv`\n\n```\n$ ./venv3.12/bin/mbs uf2conv -h\n\nusage: mbs uf2conv [-h] [-b BASE] [-f FAMILY] [-o FILE] [-d DEVICE_PATH] [-l]\n [-c] [-D] [-w] [-C] [-i]\n [INPUT]\n\npositional arguments:\n INPUT input file (HEX, BIN or UF2)\n\noptions:\n -h, --help show this help message and exit\n -b BASE, --base BASE set base address of application for BIN format\n (default: 0x2000)\n -f FAMILY, --family FAMILY\n specify familyID - number or name (default: 0x0)\n -o FILE, --output FILE\n write output to named file; defaults to \"flash.uf2\" or\n \"flash.bin\" where sensible\n -d DEVICE_PATH, --device DEVICE_PATH\n select a device path to flash\n -l, --list list connected devices\n -c, --convert do not flash, just convert\n -D, --deploy just flash, do not convert\n -w, --wait wait for device to flash\n -C, --carray convert binary file to a C array, not UF2\n -i, --info display header information from UF2, do not convert\n\n```\n\n# Internal Dependency Graph\n\nA coarse view of the internal structure and scale of\n`yambs`'s source.\nGenerated using [pydeps](https://github.com/thebjorn/pydeps) (via\n`mk python-deps`).\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Yet another meta build-system.",
"version": "3.0.4",
"project_urls": {
"Homepage": "https://github.com/vkottler/yambs"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "975fda1a137653ff5cf815cd888d7c8f111de2331568eb5a5bee62faaaa96539",
"md5": "8788568811699805e96ca337cd3621d2",
"sha256": "4b880aff602495c3f1b8d780c03fb6a8e0921f2f22035805edc35d2eba72333c"
},
"downloads": -1,
"filename": "yambs-3.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8788568811699805e96ca337cd3621d2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 67384,
"upload_time": "2024-07-05T04:12:28",
"upload_time_iso_8601": "2024-07-05T04:12:28.265901Z",
"url": "https://files.pythonhosted.org/packages/97/5f/da1a137653ff5cf815cd888d7c8f111de2331568eb5a5bee62faaaa96539/yambs-3.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fed4be4e9e03cd2ec0f66fa202fa22d0a20722f4c14d88a43c95f0f71a16e030",
"md5": "aed46fbdb652cfd59ca703bd728a8744",
"sha256": "05f567c4f2ddcb00bb6239acc357eae5df8d17cf5028c3d570a8590e757aab4d"
},
"downloads": -1,
"filename": "yambs-3.0.4.tar.gz",
"has_sig": false,
"md5_digest": "aed46fbdb652cfd59ca703bd728a8744",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 48259,
"upload_time": "2024-07-05T04:12:30",
"upload_time_iso_8601": "2024-07-05T04:12:30.596163Z",
"url": "https://files.pythonhosted.org/packages/fe/d4/be4e9e03cd2ec0f66fa202fa22d0a20722f4c14d88a43c95f0f71a16e030/yambs-3.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-05 04:12:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vkottler",
"github_project": "yambs",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "yambs"
}
JSON
