Workspace & Projects

A BitForge workspace is a git repository that contains a BitForge.toml manifest. Everything else — the BitBake config, the cloned sources and the build tree — is derived from that manifest so a fresh checkout rebuilds the same project.

Initializing a workspace

bitforge --init my-distro

--init will:

1. Create the target directory (or use the current one) and initialize a git repository.
2. Scaffold a starter layer under layers/ compatible with the chosen release.
3. Write a BitForge.toml manifest and a .gitignore.
4. Clone BitBake and the base source (OpenEmbedded-core by default) into ForgeSource/.
5. Generate conf/local.conf and conf/bblayers.conf.

Omit the name to initialize in the current directory:

mkdir my-distro && cd my-distro
bitforge --init

Caution

--init refuses to run in a non-empty directory. Pass --force to initialize anyway:

bitforge --init --force

OpenEmbedded-core vs poky

By default the workspace is based on OpenEmbedded-core. Pass --poky with a Yocto release to base it on poky instead — this also clones meta-poky and meta-yocto-bsp and sets DISTRO = "poky" in local.conf:

bitforge --init my-distro --poky scarthgap

Base	Command	Layers cloned
OpenEmbedded-core	bitforge —init my-distro	meta
poky	bitforge —init my-distro —poky <release>	meta, meta-poky, meta-yocto-bsp

When no release is given, BitForge uses scarthgap.

Project layout

Path	Tracked in git?	Purpose
BitForge.toml	Yes	The manifest you edit — workspace, layers and dependencies.
BitForge.lock	Yes	Exact commit for every dependency layer.
layers/	Yes	Your own layers (the starter layer lives here).
conf/	Yes	Generated local.conf and bblayers.conf.
ForgeSource/	No (git-ignored)	Cloned poky/OE-core, BitBake and upstream dependency layers.
build/	No (git-ignored)	BitBake’s build output (tmp, sstate-cache, downloads).

Note

ForgeSource/ and build/ are rebuilt from the manifest and lockfile, so they stay out of git. Commit BitForge.toml and BitForge.lock together — that pair is enough for a teammate to reproduce your sources.

The manifest at a glance

A freshly initialized OpenEmbedded-core manifest looks like this:

[workspace]
name = "my-distro"
bitbake = "2.8"
yocto_release = "scarthgap"

[[layers]]
name = "meta-my-distro"
path = "layers/meta-my-distro"
priority = 6

[dependency.openembedded-core.meta]
giturl = "https://git.openembedded.org/openembedded-core"
branch = "scarthgap"

• [workspace] names the project and pins the BitBake and Yocto release.
• [[layers]] entries are your layers, kept under layers/.
• [dependency.*] entries are upstream layers cloned into ForgeSource/.

See Configuration for the complete schema, and Layers & Dependencies for how to add more.

Regenerating derived files

BitForge keeps conf/bblayers.conf in sync whenever you change layers or dependencies. Running bitforge in an existing workspace re-validates the sources, ensures BitBake is present and refreshes the generated config before starting the server.