Configuration

Every workspace is described by a single BitForge.toml at its root. BitForge reads it on start and rewrites the derived conf/bblayers.conf whenever layers or dependencies change. This page documents each section.

[workspace]

Identifies the project and pins the toolchain versions.

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

Key	Type	Default	Description
name	string	—	Workspace name.
bitbake	string	”2.8”	BitBake branch to clone into ForgeSource/.
yocto_release	string	—	Default release/branch used for layers that don’t set their own ref.

[[layers]]

Your own layers, one entry per layer, scaffolded under layers/.

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

Key	Type	Description
name	string	Layer name (normalized to the meta- convention).
path	string	Path to the layer within the workspace.
priority	integer	BitBake layer priority.

Tip

Manage these with bitforge --add-layer / --remove-layer rather than editing by hand — the layer directory and bblayers.conf are updated together.

[dependency.<name>.<layer>]

Upstream layers cloned into ForgeSource/. The table is keyed by a repository name and then by each linked layer.

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

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

Key	Type	Description
giturl	string	Repository URL.
branch	string	Branch to check out (mutually exclusive with tag/commit).
tag	string	Tag to check out.
commit	string	Exact commit to check out.
path	string	Sub-directory within the repo when the layer is nested.

Note

Add and remove these with bitforge --dependency-add / --dependency-remove. The resolved commit is pinned in BitForge.lock.

[default]

The image used when --build is run without a target.

[default]
image = "core-image-minimal"

[server]

Controls the built-in web server. All keys are optional.

[server]
host = "0.0.0.0"
port = 8080
shutdown_grace_secs = 20
activity_timeout = 3
http1_keep_alive = true

Key	Type	Default	Description
host	string	”0.0.0.0”	Interface to bind.
port	integer	0 (auto)	Port to bind; 0 picks a free port.
shutdown_grace_secs	integer	20	Seconds to wait for in-flight work on shutdown.
activity_timeout	integer	3	Idle timeout in minutes.
http1_keep_alive	bool	true	Enable HTTP/1 keep-alive.
http2_keep_alive_secs	integer	unset	HTTP/2 keep-alive interval in seconds.

Full example

[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"

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

[default]
image = "core-image-minimal"

[server]
host = "0.0.0.0"
port = 8080