NAME

SYNOPSIS

DESCRIPTION

synth just-build editors/joe editors/nano editors/libreoffice

synth just-build /tmp/build.list

editors/joe
editors/nano
editors/libreoffice

ENVIRONMENT

PORTSDIR

The PORTSDIR environment variable is only checked on the very first signficant command of synth (meaning everything except help and version) when the default profile is created. It is also checked when adding new profiles. The variable dictates the default location of the ports tree with a higher priority than the standard locations.

SYNTHPROFILE

When this environment variable is set to name of an existing synth profile, that profile will be loaded when synth is launch rather than the active profile. It is a temporary override; removing the variable will allow the default profile to load again.

WHYFAIL

When this environment variable is defined to any value, the sanity check routines will provide more detail on dependency and option check failures on a separate output line.

ENTERAFTER

This environment variable only applies with the test command, and then only when a single port is specified. If both of those conditions are satisfied, and the variable has the value of:

• extract
• patch
• configure
• build
• stage
• install
• deinstall

then an interactive build will be attempted. First, all the port's prerequisites are built normally and synth will return to text mode. If everything built successfully, the specified port will build up to and including the point specified by ENTERAFTER. At that point, control will be given to the user by providing them with a tcsh shell with the current directory set at the root of the builder. When the user is done, they should terminate the shell with the exit command to signal synth to clean up and terminate. This is a developer tool to troubleshoot port build problems and it is not intended for the average user.

LOCK

This environment variable only applies with the test command. When it is defined to any value, the builder's localbase is remounted read-only prior to the configure phase and restored to read/write permissions after building is complete. This is a diagnostic tool aimed at pinpointing file system violations as a port is not supposed to write to localbase prior to staging. Note that the localbase tmpfs setting will considered as False in this mode, so building may be noticeably slower than normal.

SELFTEST

This environment variable only applies with the test command. When it is defined, the “test” target is executed as part of the build cycle; this target is not executed under any other circumstances.

FILES

synth.ini

This is the configuration file. It is automatically generated and manipulated using the interactive configuration menu. There is no need to touch this file other than to remove unwanted profiles as currently that is not possible from the program itself. It is normally located at /usr/local/etc/synth/synth.ini

<profile>-make.conf

This is an optional, user-provided file. If it exists, the builder's /etc/make.conf will be appended with the contents of this file. For the default profile, the file would normally be located at /usr/local/etc/synth/LiveSystem-make.conf

<profile>-environment

This is an optional, user-provided file. It contains a list of name-value pairs joins with an equals sign (e.g. HTTP_PROXY=http://proxyserver:8888), one pair per line. If the file exists, these variables will be defined in the builder environment. For the default profile, the file would normally be located at /usr/local/etc/synth/LiveSystem-environment

<profile>-private.key

This is one of two files required to support the signing of the repository by a local RSA key. It is the output of the openssl genrsa command; see the EXAMPLE section for how to generate it. The file permissions are required to be set at 400 as well. For the default profile, the file is normally located at /usr/local/etc/synth/LiveSystem-private.key

<profile>-public.key

This is the second of two files required to support the signing of the repository by a local RSA key. synth must confirm the public counterpart of the signing key is available because its path is required for the generated pkg repository configuration file. For the default profile, the file is normally located at /usr/local/etc/synth/LiveSystem-public.key

<profile>-signing_command

This is one of two files required to support the signing of the repository by an external signing server. It consists of a single line containing the command; see the EXAMPLE section. For the default profile, the file is normally located at /usr/local/etc/synth/LiveSystem-signing_command

<profile>-fingerprint

This is the second of two files required to support the signing of the repository by an external signing server. It consists of a single line containing the SHA 256 hash of the public key that is the counterpart of the key that signed the repository. For the default profile, the file is normally located at /usr/local/etc/synth/LiveSystem-fingerprint

<profile>-index

The introduction of flavors within FreeBSD ports destroyed the 1:1 relationship between port directories and packages. Now any port can generated any number of packages. This requires scanning every port in the tree to determine the true origin range. This is a time consuming task, so Synth caches the scan results and reuses it as long as all ports files are older than the generated index. When Synth detects the index is out-of-date or if it doesn't exist, it is automatically generated. One index exists for each profile, with the default profile index normally located at /var/cache/synth/LiveSystem-index

synth_status_results.txt

Whenever a status command is run, a list of ports that would build with the actual command is produced at /var/synth/synth_status_results.txt

synth_prefetch_list.txt

Whenever a status command is run, and the option to use suitable prebuilt packages has been selected, a list of packages that will be fetched as a result will be written to /var/synth/synth_prefetch_list.txt

index.html

For every build run, Synth installs a web summary at the Report subdirectory of the build logs directory. For the default profile, the file would be located at /var/log/synth/Report/index.html. To remotely view the web report with a browser, a web server must be present and configured to expose the logs directory. The web report is dynamic and updated 10 times per minute. The complete history is available and searchable, with quick-filters on "Built", "Failed", "Ignored" and "Skipped" fields as well as on the "No." column which is useful to examine cascaded skips. The search filter can be quickly cleared by clicking on the "Total" field.

port logs

Every single attempt at building a port results in a build log. The name of the log is always in the form of [category]___[port].log so that subsequent builds will overwrite previous attempts. They are created in the directory specified by the configuration.

hook_run_start

If this file exists, and it is executable (or it is a symbolic link that leads to an executable file) then it will be executed by synth at the start of the build. The same requirement exists for all hooks. This hook, and the next five hooks all define the following common environment variables: PROFILE, DIR_PACKAGES, DIR_REPOSITORY, DIR_PORTS, DIR_OPTIONS, DIR_DISTFILES, DIR_LOGS, DIR_BUILDBASE. Uniquely, this hook also defines PORTS_QUEUED which is the number of ports that synth will attempt to build. This file must be colated with synth.ini, so that would be /usr/local/etc/synth/hook_run_start for most installations.

hook_run_end

This hook is fired when the build completes. In addition to the common definitions, it defines PORTS_BUILT, PORTS_FAILED, PORTS_IGNORED, and PORTS_SKIPPED in the environment, which represents the results of the build.

hook_pkg_success

This hook is fired whenever a builder successfully packages a port. In addition to the common definitions, it defines RESULT=success, ORIGIN, and PKGNAME in the environment.

hook_pkg_failure

This hook is fired whenever a builder fails to package a port. In addition to the common definitions, it defines RESULT=failure, ORIGIN, and PKGNAME in the environment.

hook_pkg_ignored

This hook is fired prior to the start of a build when synth prescans the queue for ports that are to be ignored according to the ports tree. Once the build has started, this hook is never fired again. In addition to the common definitions, it defines RESULT=ignored, ORIGIN, and PKGNAME in the environment.

hook_pkg_skipped

This hook is fired whenever a package gets ignored or fails which in turns cascades into a number of ports getting removed from the build queue due to the dependency's failure. This may fire before the build starts due to ignored prescanning, or any time during the build. In addition to the common definitions, it defines RESULT=skipped, ORIGIN, and PKGNAME in the environment.

SEE ALSO

NOTES

EXAMPLE

% cd /usr/local/etc/synth
% openssl genrsa -out LiveSystem-private.key 2048
% chmod 0400 LiveSystem-private.key
% openssl rsa -in LiveSystem-private.key -out \
  LiveSystem-public.key -pubout

To activate the signing of default profile's repository with an external signing server, two files need to be created. It's assumed the signing server has already been configured as described by the pkg-repo(8) man page, and that the keys are located in the repo.pub and repo.key files. On the signing server which is 192.168.0.44 in this example:

% sha256 -q repo.pub > LiveSystem-fingerprint
% echo "/usr/bin/ssh 192.168.0.44 /usr/local/bin/sign.sh" \
  > LiveSystem-signing_command

Then move both files to /usr/local/etc/synth directory on the build server. The build server root user needs to have a passphrase-free SSH key access to the signing server in order for Synth to sign the repository.

HISTORY

synth was written entirely by John Marino ⟨marino@FreeBSD.org⟩ and released under the Internet Software Consortium license.