https://github.com/refi64/croft
ChROmium Flatpak Toolkit
https://github.com/refi64/croft
Last synced: 4 months ago
JSON representation
ChROmium Flatpak Toolkit
- Host: GitHub
- URL: https://github.com/refi64/croft
- Owner: refi64
- License: mpl-2.0
- Created: 2021-07-22T02:05:55.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2022-12-01T01:22:22.000Z (over 3 years ago)
- Last Synced: 2025-04-11T18:27:56.204Z (about 1 year ago)
- Language: Dart
- Size: 39.1 KB
- Stars: 4
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# CroFT
*Chromium Flatpak Toolkit*
CroFT is a utility for managing a Chromium source tree tied to a Flatpak
manifest, actively used for maintaining the primary Chromium Flatpak. The end
goal is to be able to, in theory, have this tool (and the workflows it supports)
shared amongst anyone else who wants to maintain some source-based Chromium
derivative Flatpak, in order to streamline routine maintenance.
## Downloads
Binary releases of this will periodically be posted to
[the releases page](https://github.com/refi64/croft/releases).
## Building
Install the Dart SDK, then run:
```
$ dart pub get
$ dart run build_runner build
$ dart2native bin/croft.dart -o croft
```
then move the `croft` binary to wherever you want.
## Configuration
CroFT requires a `~/.config/croft.yaml` to work, using the following format:
```yaml
# Map of Chromium-based Flatpak projects
projects:
chromium:
# Directory containing the Flatpak manifest and related files
manifest-dir: ~/manifests/chromium
# Filename of the Flatpak manifest
manifest-name: org.chromium.Chromium.yaml
# Module in the Flatpak manifest that builds the Chromium project itself
main-module: chromium
# Directory containing the Chromium source tree
chromium-source-root: ~/code/chromium/src
# (optional, defaults to 'docker') The docker or podman command to run
docker-command: docker
# (optional, defaults to 'false') Build a custom toolchain to configure FFmpeg
use-custom-ffmpeg-toolchain: false
# (optional) Default project name in the projects map above
default-project: chromium
```
## Basic terms
- "Component" is referring to either the root Chromium repository ("chromium")
or the FFmpeg repository inside ("ffmpeg").
- "Upstream revision" is the last revision that's part of upstream, i.e. the
revision right before any locally added commits.
## Workflow to update Chromium
### Updating the local source tree
First off, downloading the new sources. In your Chromium source tree, `git fetch
--tags`, then checkout the tag corresponding to the latest release, and `gclient
sync`. Note that, if any commits are present in the FFmpeg repository, this will
fail. You can work around that by resetting it first via `croft
destructive-reset ffmpeg upstream`, but note that **this will discard any work
in the FFmpeg repository**.
Now, the current patches in the manifest can be applied to Chromium and FFmpeg
via `croft apply-patches chromium` and `croft apply-patches ffmpeg`,
respectively. `croft apply-patches` is a thin wrapper over `git am -3`, so on
any patch conflicts, you can make changes as needed and then do `git am
--continue`.
If the upstream FFmpeg configuration was updated, it will conflict with our
FFmpeg configuration patch, so that one can be skipped via `git am --skip` and
recreated later (see below). If you already know there will be a conflict, you
can skip the configuration patch altogether via `croft apply-patches ffmpeg
--skip-ffmpeg-config`.
### Updating the FFmpeg configuration
If the FFmpeg configuration was updated and needs to be regenerated (see above),
use `croft generate-ffmpeg-config` to regenerate and commit the new
configuration. This command requires Docker or Podman in order to work.
### Exporting the patches
Once all patches are updated, run `croft export-patches chromium` and `croft
export-patches ffmpeg` to export the patches back to the manifest folder, then
you can commit and push those as desired.
## Workflow for modifying & creating patches
### Working with the upstream revision
You can use `croft get-upstream-revision` to print out the upstream revision.
`croft rebase-on-upstream chromium|ffmpeg` will open an interactive rebase
targeting said upstream revision, allowing you to rebase just the patch commits
as needed.
### Building Chromium
In order to access the Flatpak build environment, use `croft build-shell`, which
will build all the modules in the manifest *before* the main one, then open up
a shell in the resulting build environment (using `flatpak-builder --run`).
If you want to run an *entire* manifest build, you can use `croft
build-release`, which will build the entire Flatpak manifest, from top to
bottom. Due to the large size of the Chromium sources, this will also delete any
previous Chromium build directories left over in your Flatpak cache before it
starts.
## Usage on arm64 hosts
Chromium's default prebuilt toolchains, which required to generate the FFmpeg
config, only run on x64, so a custom-built toolchain needs to be used. You can
set `use-custom-ffmpeg-toolchain: true` in the project configuration and run
`croft build-ffmpeg-toolchain` in order to build a separate copy of the Chromium
build toolchain for use in generating the FFmpeg config. After that, `croft
generate-ffmpeg-config` will automatically use the new toolchain.