Welcome to the WebKit Container SDK, the all-in-one SDK for WebKit GTK/WPE port development.
It provides a fully-equipped container image ready for WebKit development
as well as scripts to run the image using podman
.
Once you entered the container, you can navigate to a WebKit checkout
and compile using ./Tools/Scripts/build-webkit [--gtk|--wpe]
, as usual.
There is extra documentation in the docs subdirectory for further information the SDK provides but the guide below will cover common usage.
- Integrate the SDK with your shell environment.
Add the following to your shell configuration file (e.g. ~/.bashrc
, ~/.zprofile
, ...)
to ensure that the ${WKDEV_SDK}
environment variable points to the correct location
of your webkit-container-sdk
Git checkout. It also extends the ${PATH}
to make the wkdev-*
scripts
provided by this repository accessible without having to specifcy full paths in the shell.
source /absolute/path/to/your/Git/checkout/of/webkit-container-sdk/register-sdk-on-host.sh
Launch a new shell, or source
your shell configuration files to verify, ${WKDEV_SDK}
now expects as intented - pointing to your webkit-container-sdk
checkout.
- Create a new wkdev container for WebKit development
Execute the following command on your host system:
wkdev-create --create-home
This will create a container named wkdev by default or a custom one with --name
and it will create a new home directory for the sdk in ${HOME}/wkdev-home
by default
or a custom one with --home
.
Within the container, the ${HOME}
directory is not equal to the host ${HOME}
directory:
${HOME}/wkdev-home
(from host) is bind-mounted into the container as /home/${USER}
.
This avoids pollution of files in your host ${HOME}
directory and for convenience
it's still exposed in the container, as ${HOST_HOME}
.
NOTE: wkdev-create
will auto-detect the whole environment: X11, Wayland, PulseAudio, etc.
and eventually needs root permissions on the host system to perform first-time-run-only
initializations (such as allowing GPU profiling, by modifying root
-owned config files, etc.)
- Enter the new wkdev container
Execute the following command on your host system:
wkdev-enter --name wkdev
After a few seconds you enter the container shell.
- Verify host system integration is working properly
You may optionally run the test script in the container, which tests various workloads:
wkdev-test-host-integration
- Compile WPE WebKit
cd "${HOST_HOME}/path/to/your/WebKit/checkout"
./Tools/Scripts/build-webkit --wpe --release
To run tests / execute MiniBrowser, try;
./Tools/Scripts/run-webkit-tests --wpe --release fast/css # Full tests take a long time
./Tools/Scripts/run-minibrowser --wpe https://browserbench.org/MotionMark1.2/
- READY!
You should check, once in a while, if there is a new upstream version of the wkdev-sdk
image available.
- Use the
wkdev-update
tool.
Run wkdev-update
and following the instructions to selectively update the base images of your local
containers. under the hood it deleted the old containers and re-creates them using the new base image
and your previous settings. NOTE: Any changes to the container filesystem will VANISH.. Modifications
to e.g. /etc
config files in the container, manually installed packages, etc. will disappear. Only the
container home directory will stay untouched.
- READY!
Since you will be regularly re-creating containers there is support for automatically running a script
after each container is created. You can do this by making a .wkdev-firstrun
script in the directory
you specify as your SDK home (${HOME}/wkdev-home
by default). This script runs as your user but has
permissions to use sudo
for tasks such as installing packages. An example script:
#!/usr/bin/env bash
# This example is a bash script but it can be any executable file.
# Install extra applications like your favorite editor.
sudo apt-get install --yes micro
# The hostname is set to the name of the container so you could
# for example have a specific one where you always work on a library.
if [[ "$(hostname -s)" == "wkdev-foo" ]]; then
jhbuild --no-interact build glib
fi
As the container is a normal Ubuntu installation there are many ways to install custom libraries however we have a solution to make this easier. JHBuild is a tool that automates downloading, building, and installing projects and is provided in the SDK.
- Build glib master
jhbuild build glib
This will do an initial build of glib and its dependencies.
- Modify and reinstall glib
All of the sources are located in ~/checkout
.
cd ~/checkout/glib
# Modify as you please
jhbuild make
Note that jhbuild make
only works in the checkout directory. If you have sources
in another location you can make a symlink matching the module name.
You can remove your modified version with jhbuild uninstall glib
though do note
that some JHBuild modules such as GStreamer are included by default and should not
be uninstalled.
We provide a small list of projects that can be easily hacked on. You can view
the projects JHBuild knows about with jhbuild list --all-modules
. The process
is identical for all of these projects.
If you want to add a new project you can make a moduleset file
to use the same workflow. Examples can be found in /jhbuild/webkit-sdk-deps.modules
(our default modules) and /jhbuild/jhbuild/modulesets/
. You can then build a
custom moduleset with jhbuild -m ~/myproject.modules build myproject
for example.
It is also possible to directly build any project like so:
jhbuild shell
# For CMake
cmake -DCMAKE_INSTALL_PREFIX=$JHBUILD_PREFIX -DCMAKE_INSTALL_LIBDIR=$JHBUILD_LIBDIR ...
# For Meson
meson setup --prefix=$JHBUILD_PREFIX --libdir=$JHBUILD_LIBDIR ...