mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2025-08-09 07:02:30 -04:00
Add intro for Builder v2
This commit is contained in:
Marta Marczykowska-Górecka
parent
941ef46054
commit
06e37e444b
8 changed files with 192 additions and 43 deletions
|
|
@ -12,14 +12,14 @@ title: Development workflow
|
|||
|
||||
A workflow for developing Qubes OS+
|
||||
|
||||
First things first, setup [QubesBuilder](/doc/qubes-builder/). This guide
|
||||
assumes you're using qubes-builder to build Qubes.
|
||||
First things first, setup [QubesBuilder](/doc/qubes-builder-v2/). This guide
|
||||
assumes you're using qubes-builder v2 to build Qubes.
|
||||
|
||||
## Repositories and committing Code
|
||||
|
||||
Qubes is split into a bunch of git repos. These are all contained in the
|
||||
`qubes-src` directory under qubes-builder. Subdirectories there are separate
|
||||
components, stored in separate git repositories.
|
||||
`artifacts/sources` directory under qubes-builder. Subdirectories there are
|
||||
separate components, stored in separate git repositories.
|
||||
|
||||
The best way to write and contribute code is to create a git repo somewhere
|
||||
(e.g., github) for the repo you are interested in editing (e.g.,
|
||||
|
|
@ -29,7 +29,7 @@ of Qubes, cd to the repo directory and add your repository as a remote in git
|
|||
**Example:**
|
||||
|
||||
~~~
|
||||
$ cd qubes-builder/qubes-src/qubes-manager
|
||||
$ cd qubes-builder/artifacts/sources/qubes-manager
|
||||
$ git remote add abel git@github.com:abeluck/qubes-manager.git
|
||||
~~~
|
||||
|
||||
|
|
@ -47,7 +47,7 @@ include your public PGP key you use to sign your tags.
|
|||
|
||||
#### Prepare fresh version of kernel sources, with Qubes-specific patches applied
|
||||
|
||||
In qubes-builder/qubes-src/linux-kernel:
|
||||
In qubes-builder/artifacts/sources/linux-kernel:
|
||||
|
||||
~~~
|
||||
make prep
|
||||
|
|
@ -66,7 +66,7 @@ drwxr-xr-x 6 user user 4096 Nov 21 20:48 kernel-3.4.18/linux-obj
|
|||
|
||||
#### Go to the kernel tree and update the version
|
||||
|
||||
In qubes-builder/qubes-src/linux-kernel:
|
||||
In qubes-builder/artifacts/sources/linux-kernel:
|
||||
|
||||
~~~
|
||||
cd kernel-3.4.18/linux-3.4.18
|
||||
|
|
@ -117,8 +117,6 @@ vi series.conf
|
|||
|
||||
#### Building RPMs
|
||||
|
||||
TODO: Is this step generic for all subsystems?
|
||||
|
||||
Now it is a good moment to make sure you have changed kernel release name in
|
||||
rel file. For example, if you change it to '1debug201211116c' the
|
||||
resulting RPMs will be named
|
||||
|
|
@ -131,34 +129,23 @@ your changes locally.
|
|||
To actually build RPMs, in qubes-builder:
|
||||
|
||||
~~~
|
||||
make linux-kernel
|
||||
./qb -c linux-kernel package fetch prep build
|
||||
~~~
|
||||
|
||||
RPMs will appear in qubes-src/linux-kernel/pkgs/fc20/x86\_64:
|
||||
RPMs will appear in
|
||||
`artifacts/repository/destination_name/package_name`
|
||||
(for example `artifacts/repository/host-fc37/linux-kernel-6.6.31-1.1/`
|
||||
|
||||
~~~
|
||||
-rw-rw-r-- 1 user user 42996126 Nov 17 04:08 kernel-3.4.18-1debug20121116c.pvops.qubes.x86_64.rpm
|
||||
-rw-rw-r-- 1 user user 43001450 Nov 17 05:36 kernel-3.4.18-1debug20121117a.pvops.qubes.x86_64.rpm
|
||||
-rw-rw-r-- 1 user user 8940138 Nov 17 04:08 kernel-devel-3.4.18-1debug20121116c.pvops.qubes.x86_64.rpm
|
||||
-rw-rw-r-- 1 user user 8937818 Nov 17 05:36 kernel-devel-3.4.18-1debug20121117a.pvops.qubes.x86_64.rpm
|
||||
-rw-rw-r-- 1 user user 54490741 Nov 17 04:08 kernel-qubes-vm-3.4.18-1debug20121116c.pvops.qubes.x86_64.rpm
|
||||
-rw-rw-r-- 1 user user 54502117 Nov 17 05:37 kernel-qubes-vm-3.4.18-1debug20121117a.pvops.qubes.x86_64.rpm
|
||||
~~~
|
||||
### Useful [QubesBuilder](/doc/qubes-builder-v2/) commands
|
||||
|
||||
### Useful [QubesBuilder](/doc/qubes-builder/) commands
|
||||
|
||||
1. `make check` - will check if all the code was committed into repository and
|
||||
if all repository are tagged with signed tag.
|
||||
2. `make show-vtags` - show version of each component (based on git tags) -
|
||||
mostly useful just before building ISO. **Note:** this will not show version
|
||||
for components containing changes since last version tag.
|
||||
3. `make push` - push change from **all** repositories to git server. You must
|
||||
set proper remotes (see above) for all repositories first.
|
||||
4. `make prepare-merge` - fetch changes from remote repositories (can be
|
||||
specified on commandline via GIT\_SUBDIR or GIT\_REMOTE vars), (optionally)
|
||||
verify tags and show the changes. This do not merge the changes - there are
|
||||
left for review as FETCH\_HEAD ref. You can merge them using `git merge
|
||||
FETCH_HEAD` (in each repo directory). Or `make do-merge` to merge all of them.
|
||||
1. `./qb package diff` - show uncommitted changes
|
||||
2. ` ./qb repository check-release-status-for-component` and
|
||||
`./qb repository check-release-status-for-template`- show version of each
|
||||
component/template (based on git tags)
|
||||
3. `./qb package sign` - sign built packages
|
||||
4. `./qb package publish` and `./qb package upload` - publish signed packages
|
||||
and upload published
|
||||
repository
|
||||
|
||||
## Copying Code to dom0
|
||||
|
||||
|
|
|
|||
160
developer/building/qubes-builder-v2.md
Normal file
160
developer/building/qubes-builder-v2.md
Normal file
|
|
@ -0,0 +1,160 @@
|
|||
---
|
||||
lang: en
|
||||
layout: doc
|
||||
permalink: /doc/qubes-builder-v2/
|
||||
redirect_from:
|
||||
- /en/doc/qubes-builder-v2/
|
||||
- /doc/QubesBuilder2/
|
||||
- /wiki/QubesBuilder2/
|
||||
ref: 311
|
||||
title: Qubes builder v2
|
||||
---
|
||||
|
||||
This is a brief introduction of using Qubes Builder v2 to work with Qubes OS
|
||||
sources. It will walk you through installing and configuring Builder v2 and
|
||||
using it to fetch and build Qubes OS packages.
|
||||
|
||||
For details and customization, use [Qubes OS v2 builder documentation](https://github.com/QubesOS/qubes-builderv2/).
|
||||
|
||||
# Overview
|
||||
|
||||
In the second generation of Qubes OS builder, container or disposable qube
|
||||
isolation is used to perform every stage of the build and release process.
|
||||
From fetching sources to building, everything is executed inside an isolated
|
||||
*cage* (either a disposable or a container) using an *executor*. For every
|
||||
command that needs to perform an action on sources, like cloning and
|
||||
verifying Git repos, rendering a SPEC file, generating SRPM or Debian
|
||||
source packages, a new cage is used. Only the signing, publishing, and
|
||||
uploading stages are executed locally outside a cage.
|
||||
|
||||
|
||||
# Setup
|
||||
|
||||
This is a simple setup for using a docker executor (a good default choice,
|
||||
if you don't know which executor to use, use docker).
|
||||
|
||||
1. First, decide what qube are you going to use for working with Qubes
|
||||
Builder v2. It can be an AppVM or a Standalone qube, with some steps
|
||||
different between the two.
|
||||
|
||||
2. Then, clone the qubes-builder v2 repository into a location of your
|
||||
choice:
|
||||
```shell
|
||||
git clone https://github.com/QubesOS/qubes-builderv2
|
||||
cd qubes-builderv2/
|
||||
```
|
||||
|
||||
3. Installing dependencies
|
||||
|
||||
Dependencies need to be installed for the qube you want to be developing
|
||||
using Qubes Builder v2 - either in its template, or in the qube itself,
|
||||
if it's a standalone.
|
||||
Dependencies are specified in `dependencies-*.
|
||||
txt` files in the main builder directory, and you can install them easily
|
||||
in the following ways:
|
||||
1. for Fedora, use:
|
||||
```shell
|
||||
$ sudo dnf install $(cat dependencies-fedora.txt)
|
||||
$ test -f /usr/share/qubes/marker-vm && sudo dnf install qubes-gpg-split
|
||||
```
|
||||
2. for Debian (note: some Debian packages require Debian version 13 or
|
||||
later), use:
|
||||
```shell
|
||||
$ sudo apt install $(cat dependencies-debian.txt)
|
||||
$ test -f /usr/share/qubes/marker-vm && sudo apt install qubes-gpg-split
|
||||
```
|
||||
|
||||
4. If you haven't used docker in the current qube, you need also to set up
|
||||
some permissions. In particular, the user has to be added to the `docker`
|
||||
group:
|
||||
```shell
|
||||
$ sudo usermod -aG docker user
|
||||
```
|
||||
Next, **restart the qube**.
|
||||
|
||||
5. Finally, you need to generate a docker image:
|
||||
```shell
|
||||
$ tools/generate-container-image.sh docker
|
||||
```
|
||||
|
||||
In an AppVM, as `/var/lib/docker` is not persistent by default, you also
|
||||
need to use bind-dirs to avoid repeating this step after reboot, adding
|
||||
the following to the `/rw/config/qubes-bind-dirs.d/docker.conf` file in
|
||||
this qube:
|
||||
|
||||
```
|
||||
binds+=( '/var/lib/docker' )
|
||||
```
|
||||
|
||||
# Configuration
|
||||
|
||||
To use Qubes OS Builder v2, you need to have a `builder.yml` configuration file.
|
||||
You can use one of the sample files from the `example-configs/` directory; for a
|
||||
more readable `builder.yml`, you can also include one of the files from that
|
||||
directory in your `builder.yml`. An example `builder.yml` is:
|
||||
|
||||
```yaml
|
||||
# include configuration relevant for the current release
|
||||
include:
|
||||
- example-configs/qubes-os-r4.2.yml
|
||||
|
||||
# which repository to use to fetch sources
|
||||
use-qubes-repo:
|
||||
version: 4.2
|
||||
testing: true
|
||||
|
||||
# each package built will have local build number appended to package release
|
||||
# number. It makes it easier to update in testing environment
|
||||
increment-devel-versions: true
|
||||
|
||||
# reduce output
|
||||
debug: false
|
||||
|
||||
# this can be set to true if you do not want sources to be automatically
|
||||
# fetched from git
|
||||
skip-git-fetch: false
|
||||
|
||||
# executor configuration
|
||||
executor:
|
||||
type: docker
|
||||
options:
|
||||
image: "qubes-builder-fedora:latest"
|
||||
|
||||
```
|
||||
|
||||
|
||||
# Using Builder v2
|
||||
|
||||
To fetch sources - in this example, for the `core-admin-client` package, you
|
||||
can use the following command:
|
||||
|
||||
```shell
|
||||
$ ./qb -c core-admin-client package fetch
|
||||
```
|
||||
|
||||
This will fetch the sources for the listed package and place them in
|
||||
`artifacts/sources` directory.
|
||||
|
||||
To build a package (from sources in the `artifacts/sources` directory), use:
|
||||
|
||||
```shell
|
||||
$ ./qb -c core-admin-client package fetch prep build
|
||||
```
|
||||
|
||||
or, if you want to build for a specific target (`host-fc37` is a `dom0`
|
||||
using Fedora 37, `vm-fc40` would be a qube using Fedora 40 etc.), use:
|
||||
|
||||
```shell
|
||||
$ ./qb -c core-admin-client -d host-fc37 package fetch prep build
|
||||
```
|
||||
|
||||
If you want to fetch entire Qubes OS sources (caution: some repositories might
|
||||
have additional requirements; you can disable repositories that are not
|
||||
needed in the `example-configs/*.yml` file you are using by commenting them
|
||||
out. In particular, `python-fido2`, `lvm` and `windows`-related repositories
|
||||
have
|
||||
special requirements), use the following:
|
||||
|
||||
```shell
|
||||
$ ./qb package fetch
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue