Ports/README.md
Serenity has software patched to run on it. These shell scripts will allow you to build that sort of software, easily. Note that you must have already built Serenity, and be in a Serenity build environment.
A list of all available ports can be found here.
Third party ports might need additional dependencies from another location.
In this case, you can point the SERENITY_PORT_DIRS variable to a local ports directory.
For example:
export SERENITY_PORT_DIRS="/path/to/port/dir/:/other/path/"
Each port has a script called package.sh which defines a name and version,
its dependencies, the required files that will be downloaded as well as
configuration/compilation options, and some other things (see
Writing ports scripts for details).
cd into its directory and run ./package.shbuild_all.sh script in this
directory. Pass clean as first argument to remove old build files
beforehand.build_installed.sh
script in this directory. This is sometimes required when LibC changes, for
example. Pass clean as first argument to remove old build files beforehand.Installed ports are being tracked in Build/<architecture>/Root/usr/Ports/installed.db (a simple text file).
You can delete this file at any time, in fact it must be edited or removed
when clearing the build directory as port dependencies may not be installed
again otherwise.
Not giving an option is equivalent to installdepends, fetch, patch,
configure, build and install, in that order. This is recommended for a
regular install.
The following options are available:
fetchBy default, download, verify, and extract the port's files.
patchApply the port's patches (patches/*.patch). A file .foo_applied is created
in workdir upon success to ensure a certain patch is only
applied once.
configureBy default, run the port's configscript (usually
configure) with configopts.
buildBy default, run make with the port's makeopts.
installBy default, run make install with the port's installopts.
shellOpen a shell in the $workdir with the build environment set.
installdependsInstall all ports from the port's depends list.
cleanBy default, remove all .out files from the port's workdir.
clean_distBy default, remove everything that's been downloaded from the port's
files list.
clean_allBy default, clean and clean_dist combined.
uninstallRemove the port's files from the Serenity build directory, if it has a plist
file.
devStart a development session with guided patch importing. This mode has a bunch of nice features:
This mode takes an extra --no-depends option, that if given, will cause the dependency
fetch and build steps to be skipped.
This mode can also assist in migrating old patches to new versions through a guided semi-automated process.
--autoSame as no option, but mark the port as having been installed automatically. This is used for dependencies.
The package.sh file is a simple Bash script that's required for each port.
Patches and other files are optional. The most basic version of such a port
script simply defines some well-known variables and looks like this:
#!/usr/bin/env -S bash ../.port_include.sh
port='foo'
version='1.2.3'
useconfigure='true'
files=(
"https://example.com/foo-${version}.tar.gz#9acd50f9a2af37e471f761c3fe7b8dea5617e51dac802fe6c177b74abf0abb5a"
)
depends=(
'bar'
'baz'
)
The script in the shebang, .port_include.sh, is where
all the magic happens.
The following variables have special functionality:
configoptsOptions passed to the port's configscript in the default
configure function.
--host=${SERENITY_ARCH}-serenity is always passed, override the configure function
if that's undesirable.
use_fresh_config_subBoolean option (false by default), will replace the config.sub pointed to by
config_sub_path as part of the patching process if set to true.
config_sub_pathsPaths to the config.sub files used by autoconf, starting at $workdir.
This is set to (config.sub) by default.
configscriptName of the script that will be run in the default configure function when
useconfigure is true.
Defaults to configure.
dependsAn array of other SerenityOS ports the port depends on and which will be
installed during the installdepends step.
For example:
depends=(
'gettext'
'ncurses'
)
filesAn array of external files required by the port, one per line.
The format of each entry is as follows:
URL#HASH
Where URL is the URL from where the file will be downloaded (using curl)
and HASH is the SHA256 hash that will be used for verification.
For example:
files=(
"https://example.com/foo-${version}.tar.xz#9acd50f9a2af37e471f761c3fe7b8dea5617e51dac802fe6c177b74abf0abb5a"
)
If a file is a compressed tar archive, a gzip compressed file or a zip compressed file, it will be extracted.
The format of each entry is as follows:
git+URL#REVISION
Where URL is the URL where the repository is located
and REVISION can be any revision qualifier that is accepted by git fetch.
For example:
files=(
'git+https://gn.googlesource.com/gn#fae280eabe5d31accc53100137459ece19a7a295'
)
icon_fileThe file to use for the port launcher icon. The icon file is assumed to have a 16x16 as well as a 32x32 layer.
installoptsOptions passed to make install in the default install function.
DESTDIR="${SERENITY_INSTALL_ROOT}" ("${SERENITY_SOURCE_DIR}/Build/${SERENITY_ARCH}/Root")
is always passed, override the install function if that's undesirable.
makeoptsOptions passed to make in the default build function.
Defaults to -j$(nproc).
patchlevelThe value for patch's -p / --strip option, see man patch for details.
Defaults to 1.
portThe "package name" of the port, usually the same as the directory this script is placed in.
prefixThe location of the ports directory, only used for the package.db file for
now. Don't override this in ports contributed to Serenity.
Defaults to $SERENITY_SOURCE_DIR/Ports.
useconfigureThe configure step will run pre_configure and configure when this is set
to true, and simply skip them otherwise.
Defaults to false.
versionThe version of the port. Written to package.db, and usually used with
variable interpolation in files where the version is part of the
filename.
workdirThe working directory used for executing other commands via run as well as
cleanup. Usually the directory name of the unpacked source archive.
Defaults to $port-$version.
The various steps of the port installation process are split into individual Bash functions, some of which can be overridden to provide custom behavior, like this:
build() {
run mybuildtool --foo --bar
}
The following can be overridden, the names should be self-explanatory as they mostly match the available options:
pre_fetchpost_fetchpre_patchpre_configureconfigurepost_configurebuildpre_installinstallpost_installcleanclean_distclean_allA few (non-overridable) util functions are available as well:
runLog the command and run it in the port's workdir.
run_nocdLog the command and run it in the current working directory
(i.e. Ports/$port).
run_replace_in_fileReplace something in a file (using a Perl regular expression), like this:
run_replace_in_file "s/define FOO 1/undef FOO/" config.h
You can either:
package.sh scriptSome videos of Andreas adding new ports can be found on YouTube, they might help you understand how this usually works: