{"id":18497251,"url":"https://github.com/bottlerocket-os/twoliter","last_synced_at":"2026-01-07T03:13:08.204Z","repository":{"id":156714664,"uuid":"633089849","full_name":"bottlerocket-os/twoliter","owner":"bottlerocket-os","description":"A build tool for customizing Bottlerocket","archived":false,"fork":false,"pushed_at":"2025-08-19T22:30:16.000Z","size":4721,"stargazers_count":30,"open_issues_count":98,"forks_count":35,"subscribers_count":25,"default_branch":"develop","last_synced_at":"2025-08-20T00:24:56.238Z","etag":null,"topics":["bottlerocket"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bottlerocket-os.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-APACHE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2023-04-26T18:57:59.000Z","updated_at":"2025-08-19T22:30:21.000Z","dependencies_parsed_at":"2023-07-10T07:16:27.590Z","dependency_job_id":"2ac01c98-05b1-4962-89c0-44314169743f","html_url":"https://github.com/bottlerocket-os/twoliter","commit_stats":null,"previous_names":[],"tags_count":69,"template":false,"template_full_name":null,"purl":"pkg:github/bottlerocket-os/twoliter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bottlerocket-os%2Ftwoliter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bottlerocket-os%2Ftwoliter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bottlerocket-os%2Ftwoliter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bottlerocket-os%2Ftwoliter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bottlerocket-os","download_url":"https://codeload.github.com/bottlerocket-os/twoliter/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bottlerocket-os%2Ftwoliter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279002104,"owners_count":26083307,"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-09T02:00:07.460Z","response_time":59,"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":["bottlerocket"],"created_at":"2024-11-06T13:34:00.046Z","updated_at":"2025-12-12T11:56:49.944Z","avatar_url":"https://github.com/bottlerocket-os.png","language":"Rust","readme":"# Twoliter\n\nA build tool for creating custom [Bottlerocket] variants.\nSee the [design doc] describing how Twoliter works.\nWe welcome ideas and requirements in the form of issues and comments!\n\n[Bottlerocket]: https://github.com/bottlerocket-os/bottlerocket\n[design doc]: docs/design/README.md\n\n## For Maintainers\n\nThis section includes information for maintainers about testing and releasing Twoliter.\n\n## Unit Tests and Integration Tests\n\nIf you run `cargo test` you will get the default features which includes the feature `integ-tests`.\nThese will be quite slow as some of them do complete builds.\nIf you don't have time for that, run `cargo test --no-default-features` to run only the fast tests.\n\n## Testing the Binary in a Project\n\nIn general, if you have changes to Twoliter and want to try them out in a Twoliter project, it is as simple as building the Twoliter binary and using it in your project.\nDifferent projects will have different ways of making sure the correct Twoliter binary is being used.\nFor example, Bottlerocket has a script and Makefile.toml variables that ensure the correct version of Twoliter is being used to build Bottlerocket.\nThe following sections describe how to use those mechanisms to use a non-released version of Twoliter.\n\n### Testing Twoliter Changes in the Bottlerocket Repo\n\nThe process of testing changes to Twoliter in Bottlerocket is as follows:\n- Commit your changes. This can be either a local commit or a commit on a git fork.\n- In the Bottlerocket git repo\n  - Remove the existing Twoliter binary if it exists.\n  - Ensure the [nightly rust toolchain] is installed and enabled.\n  - Run any/all `cargo make` commands with the following environment\n    variables.\n\n[nightly rust toolchain]: https://rust-lang.github.io/rustup/concepts/channels.html#working-with-nightly-rust\n\n```sh\n# The URL to the Twoliter git repository. This can be anything that git remote add would accept.\n# Here we are using a path on the local filesystem.\nTWOLITER_REPO=file:///home/myuser/repos/twoliter\n# The sha of the commit you want to use. Make sure changes have been committed!\nTWOLITER_VERSION=a8b30def\n# These need to be set as follows.\nTWOLITER_ALLOW_SOURCE_INSTALL=true\nTWOLITER_ALLOW_BINARY_INSTALL=false\nTWOLITER_SKIP_VERSION_CHECK=true\n```\n\nSo, for example, to build a Bottlerocket image using a commit on a fork, I would look like this:\n\n```sh\n  rm -rf tools/twoliter\n  cargo make -e=TWOLITER_REPO=https://github.com/webern/twoliter \\\n    -e=TWOLITER_VERSION=11afef09 \\\n    -e=TWOLITER_ALLOW_SOURCE_INSTALL=true \\\n    -e=TWOLITER_ALLOW_BINARY_INSTALL=false \\\n    -e=TWOLITER_SKIP_VERSION_CHECK=true \\\n  build-variant\n```\n\n### Alternative Method of Testing in the Bottlerocket Repo\n\nAnother way you can test your Twoliter changes in the Bottlerocket repo is by building twoliter and\nmoving it into the right place, then telling `cargo make` not to install Twoliter at all.\n\nFor example, if you have set `TWOLITER_REPO` and `BOTTLEROCKET_REPO` to the respective local git repositories, then:\n\n```shell\ncd $TWOLITER_REPO\ncargo build --release --package twoliter --bin twoliter\nrm -rf $BOTTLEROCKET_REPO/tools/twoliter\nmkdir -p $BOTTLEROCKET_REPO/tools/twoliter\ncp $TWOLITER_REPO/target/release/twoliter $BOTTLEROCKET_REPO/tools/twoliter\n\ncd $BOTTLEROCKET_REPO\n\ncargo make \\\n    -e=TWOLITER_ALLOW_SOURCE_INSTALL=false \\\n    -e=TWOLITER_ALLOW_BINARY_INSTALL=false \\\n    -e=TWOLITER_SKIP_VERSION_CHECK=true \\\n    build-variant\n```\n\n## Releasing\n\nA release consists of a semver tag in the form `v0.0.0`.\nWe also use release-candidate tags in the form `v0.0.0-rc1`.\n\nWe use a fork of `cargo-dist` to facilitate binary releases.\nThe purpose of the `cargo-dist` fork is to enable cross-compilation with `cross`\nWe do not release Twoliter into `crates.io`.\n\n`cargo-dist` is run by GitHub Actions, and the release workflow requires an additional approver to run the release action.\n\nTo perform a release:\n\n- Create and merge a PR that bumps the version and changelog like [this one].\n  This commit should use the desired `rc` version for the `twoliter` crate, e.g. `0.0.4-rc1`.\n- Push a release-candidate tag matching the selected version, e.g. `v0.0.4-rc1`.\n- That will create a GitHub Actions workflow which will create a GitHub release and attach binaries.\n- An additional approver must navigate to the [Actions tab] and approve the Release workflow.\n- Create a Bottlerocket PR ([example]) that uses the new version of Twoliter.\n  At first, your PR will use the candidate tag.\n  Before merging to the Bottlerocket repo, you will use the final release tag.\n- Test Twoliter in Bottlerocket\n  - `cargo make`\n  - `cargo make ami`\n  - `cargo make test --help`\n  - More extensive testing if needed.\n  - Note: If you want to use your local version of Twoliter to build Bottlerocket.\n    - Delete the existing install of Twoliter if it exists.\n    - Commit and push your code to your fork of Twoliter. For example: https://github.com/YOUR_GIT_ALIAS/twoliter\n    - Set the following Environment variables\n      - TWOLITER_REPO = Your Twoliter Repository link.\n      - TWOLITER_VERSION = Hash of the commit pushed to your Twoliter repository.\n      - TWOLITER_ALLOW_SOURCE_INSTALL = True, as we want to do a source install.\n      - TWOLITER_ALLOW_BINARY_INSTALL = False, as we do want to use a Twoliter binary.\n      - TWOLITER_SKIP_VERSION_CHECK = True, as we do not want to use a certain Twoliter binary version.\n  - For example,\n```\n  rm -rf tools/twoliter\n  cargo make -e=TWOLITER_REPO=https://github.com/YOUR_GIT_ALIAS/twoliter \\\n    -e=TWOLITER_VERSION=HASH_OF_COMMIT \\\n    -e=TWOLITER_ALLOW_SOURCE_INSTALL=true \\\n    -e=TWOLITER_ALLOW_BINARY_INSTALL=false \\\n    -e=TWOLITER_SKIP_VERSION_CHECK=true\n```\n- When it's working, create a new PR to the Twoliter repo dropping the `-rc` in the version string.\n- Merge the Twoliter PR and push a finalized tag, e.g. `v0.0.4`.\n- An additional approver must navigate to the [Actions tab] and approve the Release workflow.\n- Once the GitHub Actions workflow finishes, update the Bottlerocket PR to your finalized tag.\n- Merge the Bottlerocket PR\n\n[this one]: https://github.com/bottlerocket-os/twoliter/pull/91\n[example]: https://github.com/bottlerocket-os/bottlerocket/pull/3480\n[Actions tab]: https://github.com/bottlerocket-os/twoliter/actions\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbottlerocket-os%2Ftwoliter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbottlerocket-os%2Ftwoliter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbottlerocket-os%2Ftwoliter/lists"}