Skip to main content

# Flapjack #

Flapjack is a tool that lets you hack on one or more of the components
inside a flatpak runtime.
You can make changes to the components and build a new "development
SDK" with your changed components.
You can then test your flatpak apps by running them against the
development SDK.

## Setting up your development environment ##

Install Flapjack with `pip3 install --user flapjack`.

Flapjack requires only Python 3.4 or later, Git, Flatpak, and
Flatpak-builder.
It does not require any other Python modules to run.
For installation, it requires pip or setuptools.

If you want, create a configuration file in `~/.config/flapjack.ini`.
Use the [`example.flapjack.ini`][1] as a template if you need to.
Out of the box, Flapjack is configured to work on the core platform
from the GNOME SDK.
The example file shows how to configure it for the Endless OS apps SDK.

Run `flapjack setup` to perform one-time setup.
This will install the base SDK that you are going to be modifying.
It will probably take a while.

## Using Flapjack ##

Flapjack is a command-line tool with several subcommands.
Run `flapjack --help` to get an overview of the subcommands.

The most basic thing you can do is to build your development runtime.
Run `flapjack build` to do that.
This builds a runtime without any modified components.
It's basically equivalent to the base SDK (although you can add
developer tools to it; see "Developer tools" below.)

Now, `flapjack run` will run a flatpak app against the development SDK
that you just built: for example, `flapjack run org.gnome.gedit`.
Since nothing has changed yet, this will not be very enlightening.

## Developing a component ##

As a tutorial, we will perform the [well-known trick of running GEdit
with all the labels upside-down][2].
We'll build a development SDK with a modified GTK that will do this,
and run GEdit against the development SDK.

For this, you have to indicate that you want to modify GTK.
Do this with `flapjack open gtk3`.
This will put a git clone of GTK in `~/flapjack/checkout/gtk3`.

For a list of other modules that are available to modify, do
`flapjack list`.
Note that `gtk3` is now shown with an asterisk, indicating that it is
open.

Let's now make the change in GTK.
Go into `~/flapjack/checkout/gtk3/gtk/gtklabel.c`, search for
`label_props[PROP_ANGLE]`, and change the last `0.0` in that paragraph
to `180.0` to set the default angle for labels to be upside-down.
Also add `priv->angle = 180.0;` to the end of the `gtk_label_init`
function.

Then, save the file and do `flapjack build` to build the development SDK
again with our modified copy of GTK.
You don't need to make a git commit, Flapjack will build whatever the
current state of the tree is.
When it's done, `flapjack run org.gnome.gedit` should run GEdit against
the development SDK, which now shows labels upside-down!

To test your modifications, you can also do `flapjack test gtk3` to run
`make check` while building GTK.
If a module's tests don't usually run in a sandbox, then they might not
work out of the box.
The `flapjack test` command has some extra options in case you need to
debug the tests or run distcheck instead.
Use `flapjack test --help` to see them.

When you are done modifying GTK, do `flapjack close gtk3` and open
a different module.
You can also have more than one module open at the same time, since it
often happens that changes in one module have effects on another one.

# Miscellaneous commands #

Doing `flapjack shell` will open a shell inside the sandbox of the
development SDK that you have built.
You can use this to poke around and see what's installed.

The `flapjack update` command will make sure you have the latest version
of the base SDK and do a `git fetch` in all of your checkouts.

# Developer tools #

You can also include extra developer tools in your development SDK.
As an example, here's how to include the [`jq`][3] utility.

Add this to your `~/.config/flapjack.ini` configuration file:
```
dev_tools_manifest = ${workdir}/devtools.json
```

Then, create a file in `~/flapjack/devtools.json` with the following
contents:
```json
[
{
"name": "jq",
"sources": [
{
"type": "archive",
"url": "https://github.com/stedolan/jq/releases/download/jq-1.5/jq-1.5.tar.gz",
"sha256": "c4d2bfec6436341113419debf479d833692cc5cdab7eb0326b5a4d4fbe9f493c"
}
]
}
]
```

Run `flapjack build`.
Even though no modules are open for development, the development SDK
sandbox will still contain the `jq` tool.
You can verify this with `flapjack shell`.

## Tab completion ##

### System installation ###

If you prefer a system-wide installation, clone this repository and
then run:

```
sudo python setup.py install_completions
```

### User installation ###

Download the [`flapjack.bash-completion`][4] script.

Then to test out the completion without "installing" it, just source
the file directly, like so:

```
source ~/path/to/flapjack.bash-completion
```

After you do that, tab completion will immediately be made available
in your current shell. But it won't be available next time you log in.

To install it, add the line above to your `.bashrc`.

[1]: https://github.com/endlessm/flapjack/blob/master/example.flapjack.ini
[2]: http://www.youtube.com/watch?v=70Kl9ft5DGA&t=40m4s
[3]: https://stedolan.github.io/jq/
[4]: https://github.com/endlessm/flapjack/blob/master/build/flapjack.bash-completion


Metadata

Release files for flapjack 0.1.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for flapjack 0.1.5
File Size Uploaded Provenance Actions
flapjack-0.1.5.tar.gz 24.1 kB Without provenance Details for flapjack-0.1.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for flapjack 0.1.5
File Interpreter ABI Platform Actions
flapjack-0.1.5-py2.py3-none-any.whl Python 2, Python 3 none any Details for flapjack-0.1.5-py2.py3-none-any.whl

Total release size: 39.9 kB

Release files / flapjack-0.1.5.tar.gz

Download URL flapjack-0.1.5.tar.gz
Size 24.1 kB
Tags Source
SHA-256 checksum
How to use checksums
b5e84d0ded6f3f7d6c445c7688417a68a682877abbe3b83395f80fae55da5768
BLAKE2b-256 checksum
How to use checksums
13b16bf39ef28fc29b674bf1c09ddbbe7118469e5b5833cdc76832e7dd4181ae
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/1.11.0 pkginfo/1.4.2 requests/2.18.4 setuptools/39.2.0 requests-toolbelt/0.8.0 tqdm/4.23.4 CPython/3.5.2

Release files / flapjack-0.1.5-py2.py3-none-any.whl

Download URL flapjack-0.1.5-py2.py3-none-any.whl
Size 15.8 kB
Tags Python 2 Python 3
SHA-256 checksum
How to use checksums
9534647f6f84d05561d80acdc776762128e5ef7eebb39622efe9b70d09619e81
BLAKE2b-256 checksum
How to use checksums
926ef7362fa02e0a6d5304da21e05da106abf580873a3e9e431eb117990210e3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/1.11.0 pkginfo/1.4.2 requests/2.18.4 setuptools/39.2.0 requests-toolbelt/0.8.0 tqdm/4.23.4 CPython/3.5.2

Security for flapjack 0.1.5

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page