{"id":22105148,"url":"https://github.com/desultory/gentree","last_synced_at":"2025-10-12T03:30:24.563Z","repository":{"id":264401278,"uuid":"893257027","full_name":"desultory/genTree","owner":"desultory","description":"Generates a filesystem tree in a namespace using portage","archived":false,"fork":false,"pushed_at":"2025-06-07T04:19:06.000Z","size":311,"stargazers_count":18,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-06-07T05:23:52.173Z","etag":null,"topics":["containerization","gentoo-portage","namespace","oci-images","tar"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/desultory.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,"zenodo":null}},"created_at":"2024-11-24T00:01:50.000Z","updated_at":"2025-05-13T17:49:27.000Z","dependencies_parsed_at":null,"dependency_job_id":"d8588ce4-b878-42f6-9c0d-a2796f8ffadf","html_url":"https://github.com/desultory/genTree","commit_stats":null,"previous_names":["desultory/gentree"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/desultory/genTree","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/desultory%2FgenTree","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/desultory%2FgenTree/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/desultory%2FgenTree/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/desultory%2FgenTree/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/desultory","download_url":"https://codeload.github.com/desultory/genTree/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/desultory%2FgenTree/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279010148,"owners_count":26084692,"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","status":"online","status_checked_at":"2025-10-12T02:00:06.719Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["containerization","gentoo-portage","namespace","oci-images","tar"],"created_at":"2024-12-01T06:38:48.522Z","updated_at":"2025-10-12T03:30:24.315Z","avatar_url":"https://github.com/desultory.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# genTree\n\ngenTree generates a filesystem tree in a namespace using portage.\n\ngenTree-server serves the package cache and can be used to queue new builds using genTree.\n\n## Usage\n\n`genTree \u003cconfig file\u003e [--debug, -d]`\n\nex. `genTree nginx.toml`\n\n### Importing seeds\n\nA seed must be imported before genTree can be used, whis is done with `genTree-import-seed`:\n\n\u003e `genTree-import-seed \u003csystem root\u003e \u003cseed name\u003e [conf_root]\n\n* `system root` - The system root to import, can be a stage3 tarball or a directory.\n* `seed name` - The seed name to use.\n* `conf_root` - Alternate configuration root to use.\n\n\u003e The `conf_root` is `~/.local/share/genTree` by default\n\nex. `genTree-import-seed stage3.tar.xz stage3-openrc .`\n\n### Syncing repos\n\nBy default, repos at `~/.local/share/genTree/repos` are used, and must be created with:\n\n`genTree-exec \u003cseed_name\u003e emerge --sync` \n\n\u003e Any sync method can be used.\n\n\u003e System repos can be used by setting `bind_system_repos` to true in the config.\n\n### Updating seeds\n\nSeeds can be updated with `genTree-update-seed \u003cseed name\u003e [alternate update arg string]`.\n\nex. `genTree-update-seed stage3-openrc`\n\n\u003e By default, \"--jobs 4 --update --deep --newuse --changed-use --with-bdeps=y --usepkg=y @world\" is used.\n\u003e The update string can be defined with `seed_update_args` in the default config.\n\n### Executing commands in a seed\n\nCommands can be execued in a seed using `genTree-exec [--persistent] \u003cseed name\u003e \u003ccommand\u003e`.\n\nBy default, this will execute the command in an overlay, so it only persists in the upper dir. `--persistent` can be used to execute the command directly in the seed root.\n\n### Adding crossdev support\n\nCrossdev support can be added to a seed with `genTree-init-crossdev \u003cseed name\u003e \u003ctarget-tuple\u003e`.\n\nex. `genTree-init-crossdev stage3-openrc aarch64-unknown-linux-gnu`\n\n\u003e The target tuple must be a valid crossdev target.\n\n### Removing builds\n\nTo remove old build tarballs, use `genTree-clean-builds`.\n\n`~/.local/share/genTree/builds/` is use by default, but an alternate build dir can be passed with the first arg.\n\n\u003e This is equivalent to `rm ~/.local/share/genTree/builds/*.tar`\n\n## Server usage\n\ngenTree can serve binpkgs using `aiohttp` with genTree-server.\n\n`genTree-server \u003cseed name\u003e [--debug, -d] [-a --address \u003caddress\u003e] [--port \u003cport\u003e] [--crossdev-target -c] [--profile -p] [--build-tag -t]`\n\nex. `genTree-server stage3-openrc -a 0.0.0.0`\n\nBuilds can be added to a queue using `/pkg?pkg=\u003cpkg\u003e` and viewed using `/queue`. \n\n## Configuration\n\nExample build configuration file:\n\n```\n# nginx.toml\n\n# name = \"nginx\"  # The name is set to the filename without extension by default\n# output_file = \"nginx.tar\"  # The output file is set to the name with a .tar extension by default\n\n# A seed must be defined\nseed = \"stage3-openrc\"\n\n# profile = \"default/linux/amd64/23.0\"  # Set the profile\n\nbases = [\"tini\", \"gcc\"]\n\npackages = [\"www-servers/nginx\"]\nunmerge = [\"sys-devel/gcc\"]\n\n[env]\nuse = \"nginx\"\n\n[clean_filter_options]\ncharmaps = true  # Delete charmaps before packing\n\n[tar_filter_options]\nlocales = true # Filter locales when packing\n```\n\n* `packages` (list) - The packages to emerge.\n* `unmerge` (list) - The packages to unmerge.\n* `deplean` (false) - Run depclean --with-bdeps=n after emerging.\n* `rebuild` (false) - Force a rebuild of the layer.\n\n### Defaults\n\nThe default config is set in `\u003cmodule_path\u003e/defaults.toml`, and is merged with:\n\n* `/etc/genTree/config.toml`\n* `~/.config/genTree/config.toml`\n\n\u003e Values which are set to None will check DEFAULTS for a value.\n\nThe following defaults cannot be set:\n\n* `name` - This must be set per build/layer.\n* `bases` - ''\n* `packages` / `unmerge` - ''\n* `whiteouts` / `opaques` - Handled by filters\n* `config_file` - Doesn't make sense to have a default (for inheriting)\n* `build_tag` - Used for additional override profiles, as a key.\n* `parent` - Set by the parent when adding a base.\n\nThe following defaults inheritance can be configured:\n* `env.features` - Toggled with `inherit_features`\n* `env.use` - Toggled with `inherit_use`\n* `env.common_flags` - as well as each common flag type, like cflags, cxxflags, etc.\n  - When a `crossdev_target` is set, not used unless `crossdev_use_env` is true.\n* `crossdev_env` - Environment variables to set for crossdev, same as env.\n\n\u003e The `env` dict is used to set environment variables including INHERITED_CONFIG, ENV_VARS, and DEF_ARGS\n\n\u003e Crossdev profiles are set by key name, using the target tuple as the value.\n\n```\n# ~/.config/genTree/config.toml\n\nseed = \"openrc-hardened\"\nprofile = \"default/linux/amd64/23.0/no-multilib/hardened\"\n\n[crossdev_profile]\naarch64-unknown-linux-gnu = \"default/linux/arm64/23.0\"\n\n[env]\ncpu_flags_x86 = \"aes avx avx2 f16c fma3 mmx mmxext pclmul popcnt rdrand sha sse sse2 sse3 sse4_1 sse4_2 sse4a ssse3 vpclmulqdq\"\ncommon_flags = \"-march=native -flto -O3 -pipe\"\n\n[default.openrc-hardened.pi3]\ncrossdev_target = \"aarch64-unknown-linux-gnu\"\n\n[default.openrc-hardened.pi3.crossdev_env]\ncommon_flags = \"-march=armv8-a+crc -mtune=cortex-a53 -flto -O3 -pipe\"\n\n[default.openrc-desktop]\nprofile = \"default/linux/amd64/23.0/desktop\"\n\n[default.openrc-desktop-generic]\npackage_tag = \"generic\"\nprofile = \"default/linux/amd64/23.0/desktop\"\n\n[default.openrc-desktop-generic.env]\ncommon_flags = \"-flto -O3 -pipe\"\n\n```\n\n### Bases\n\nBases are configurations used as a base for another config.\n\nBases layer contents are extracted to the lower_dir of the build layer's overlayfs mount.\n\n\u003e Builtin bases such as `tini`, `glibc`, and `base` can be specified without a suffix to be used\n\nThe path to a base file can be specified for custom bases.\n\n#### Inheritance\n\n* `inherit_use` (true) - Inherit USE flags from the parent.\n* `inherit_features` (true) - Inherit FEATURES from the parent.\n* `inherit_env` (true) - Inherit misc environment variables from the parent.\n* `inherit_config` (false) - Inherit the configuration root from the parent.\n\n\u003e `inherit_env` controls inheritance from `DEF_ARGS` (filter options and emerge args).\n\n### filters\n\nSeveral filters are available for cleaning and packing packing layer tarballs.\n\n* `refilter` (true) - Reapply all filters to the final tarball.\n\n#### Path filters\n\nPath filters are used to remove files and directories before packing.\n\nThese arguments are set under the `clean_filter_options` dict.\n\n* `man` (true) - Filters man pages.\n* `docs` (true) - Filters documentation.\n* `include` (true) - Filters headers/includes.\n* `charmaps` (true) - Filters charmaps.\n* `completions` (true) - Filters shell completions.\n* `locales` (false) - Filters locales.\n* `vardbpkg` (false) - Filters `/var/db/pkg`.\n\n\u003e `refilter` can be used to reapply filters to the final tarball.\n\n#### Tar filters\n\nTar filters are used to filter items added to the tarball.\n\nThey are set under the `tar_filter_options` dict; any path filter can be used in addition to:\n\n* `whiteouts` (true) - Handles OCI whiteouts. (.wh. files)\n* `dev` (true) - Filters character and block devices.\n\n### Profile\n\nThe profile can be set using:\n\n* `profile` (default/linux/amd64/23.0) - The profile to use.\n* `profile_repos` (gentoo) - The repository source for the profile.\n\n### emerge args\n\narguments with values can be set like:\n\n```\n[emerge_args]\njobs = 4\n```\n\n\n### emerge bools\n\nboolean operators to the `emerge` commad can be set using:\n\n```\n[emerge_bools]\nverbose = true\nwith_bdeps = false\n```\n\n\u003e Operators which cannot be set =n should be defined in PORTAGE_PLAIN_BOOLS\n\n### Environment Variables\n\nEnvironment variables can be set using the `env` dict.\n\nThe following variables can be used as sets or strings:\n\n* `use` (set) - USE flags to set.\n* `features` (set) - FEATURES to set.\n* `binpkg_format` (gpkg) - The binary package format to use.\n* `cpu_flags_{x86,arm,ppc}` (set) - CPU flags to set.\n* `common_flags` (set) - Common flags to set (appended to CFLAGS, CXXFLAGS, etc.)\n* `cflags` (str) - CFLAGS to set.\n* `cxxflags` (str) - CXXFLAGS to set.\n* `fcflags` (str) - FCFLAGS to set.\n* `fflags` (str) - FFLAGS to set.\n\n\u003e The `use` and `features` variables are sets which can interpret adding and removing flags using `+` and `-` prefixes.\n\nex:\n```\n[env]\nuse = \"-dracut ugrd\"  # The same as [\"-dracut\", \"ugrd\"]\nfeatures = [\"test\", \"-test\"]  # Add and remove test (NOOP)\nfoo_arg = \"bar\"  # Set the variable foo_arg to bar\ncommon_flags = \"-O3 -pipe -march=native -flto\"  # Set common flags\n\n```\n\n## Mounts\n\nSeveral components are mounted into the build namespace as read-only bind mounts:\n\n* `bind_system_repos` (false) - mounts the path `system_repos` to `/var/db/repos`.\n\n### seed (sysroot) overlay\n\nA seed must be defined in the top level config. Seeds are used as the lower layer in an overlay which is chrooted into.\n\nThis layer will persist between builds, and will not be cleaned unless `clean_seed` is set to true.\n\n* `clean_seed` (false) - Clean the seed overlay upper dir before building.\n* `ephemeral_seed` (false) - Mount the seed overlay on a tmpfs.\n\n### Config overlay\n\nConfiguration overrides to be mounted over `/etc/portage` can be specified using:\n\n* `config_overlay` (str) - The name of the configuration overlay to use (from `config_dir`).\n* `inherit_config` (false) - Inherit a config root from the seed.\n\n### Build overlay\n\nThe build are performed in overlays which are mounted over `/builds` in the namespace, and under `conf_root`/builds on the host.\n\n\u003e `conf_root` is ~/.local/share/genTree by default\n\nThe upper_dir is used to build layers between stages, and the mount point is used for the outermost layer.\n\n* `clean_build` (true) - Clean the build overlay before building.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdesultory%2Fgentree","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdesultory%2Fgentree","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdesultory%2Fgentree/lists"}