Building OmniOS Packages

Warning

There is no guarantee that packages in this repository build correctly on OmniOS releases earlier than r151046. If you wish to build on older releases, check out the pre-r151046 tag (or the pre-r151038 tag respectively if you want to build on releases earlier than r151038).

Introduction

The purpose of this document is to introduce building packages for the "OmniOS Extra IPS Repository".

The "OmniOS Extra IPS Repository" offers a simple way for administrators to install applications. Like everything else about the OmniOS Community Edition project, it is a volunteer effort. It is important to keep this in mind when reading this document.

The "OmniOS Extra IPS Repository" is open to all, anyone may submit a new package, or volunteer to maintain an existing or un-maintained package. No special commit privileges are needed and assistance is available if needed.

Prepare to build packages for OmniOS

The objective of this section is to prepare a build environment and introduce the build.sh and local.mog files. After this, an experimental build can be run with an example package.

Requirements
Create the build environment
Create a build directory and its build files
Build the helloworld package

Requirements

To create packages for the "OmniOS Extra IPS Repository", the following is necessary:

Virtual or physical system running the latest OmniOS release, preferably the latest "Bloody Release".
The system should have a minimum of 2GB of RAM.
"OmniOS Extra Build Tools" This can be installed with the following command:

# pkg install ooce/extra-build-tools

A GitHub account.

Create the build environment

Fork the "OmniOS Extra IPS Repository"

If help is needed with this, please see: https://help.github.com/en/github/getting-started-with-github/fork-a-repo

Create a local repository on the build system

In a suitable directory, clone the fork of the "OmniOS Extra IPS Repository", that was created in the previous step.

$ git clone github.com/github_account/omnios-extra
$ cd omnios-extra

The "OmniOS Extra IPS Repository" consists of the following 4 directories:

Directory	Purpose
build	This is where all the build and associated files reside.
doc	This is where auxiliary files reside, for the management of the "OmniOS Extra IPS Repository".
lib	This is where the build system framework tools reside.
tools	This is where auxiliary programs reside, for use in checking package builds.

Create a build directory and its build files

In this section, the ubiquitous helloworld will be packaged for OmniOS.

Create a `git branch` and a build directory

Before creating any new package, it is necessary to create a new git branch for its build files. The reason being, is that when the package is later submitted for inclusion into the "OmniOS Extra IPS Repository", only a "Pull Request" from a git branch will be accepted.

Name the git branch after the package name.

$ git branch helloworld
$ git checkout helloworld

To create the build directory for the helloworld package, create a new directory under the build directory in the cloned "OmniOS Extra IPS Repository".

$ mkdir build/helloworld
$ cd build/helloworld

Create the build files

Every package relies on 2 files to complete a build, build.sh & local.mog. These are created as follows:

$ touch build.sh local.mog
$ chmod +x build.sh

As build.sh is a bash shell script, it is set as an executable.

Once these empty files are created, the following templates can be used to create the helloworld build files:

`build.sh`

#!/usr/bin/bash
#
# {{{ CDDL HEADER
#
# This file and its contents are supplied under the terms of the
# Common Development and Distribution License ("CDDL"), version 1.0.
# You may only use this file in accordance with the terms of version
# 1.0 of the CDDL.
#
# A full copy of the text of the CDDL should have accompanied this
# source. A copy of the CDDL is also available via the Internet at
# http://www.illumos.org/license/CDDL.
# }}}

# Copyright YYYY your name/organisation

. ../../lib/build.sh

PROG=helloworld
VER=0.1
PKG=ooce/application/helloworld
SUMMARY="Hello, World! - A global salutation"
DESC="Hello, World! is a computer program that outputs the \
message 'Hello, World!'"

set_arch 64

set_mirror "https://pbdigital.org/ips-src/"
set_checksum sha256 "c6bdfebe1b9f27fc90a24348aa3492558d2bf5b0e2c366a9b6f9ec9f50b74917"

# create package functions
init
download_source $PROG $PROG $VER
prep_build
build
strip_install
make_package
clean_up

# Vim hints
# vim:ts=4:sw=4:et:fdm=marker

`local.mog`

#
# This file and its contents are supplied under the terms of the
# Common Development and Distribution License ("CDDL"), version 1.0.
# You may only use this file in accordance with the terms of version
# 1.0 of the CDDL.
#
# A full copy of the text of the CDDL should have accompanied this
# source. A copy of the CDDL is also available via the Internet at
# http://www.illumos.org/license/CDDL.

# Copyright YYYY your name/organisation

license LICENCE license=CDDL

The contents of these files will be discussed thoroughly in the "OmniOS Extra Build System" section.

Build the `helloworld` package

For the helloworld package, the above build.sh & local.mog templates are enough to build the OmniOS package.

In fact, for a robust program like tcpdump, the build.sh was not much more complicated than the above templates. A lot of knowledge of the build system can be gained browsing the various build.sh files in the build directory.

From the current helloworld directory, the helloworld package can be built from the build.sh as follows:

$ ./build.sh

Note: No special privileges are need to create a package from the build system. Nor is it advised to create packages as the root user.

This will build the helloworld package, through all its various stages, terminating with the publishing of the helloworld package.

The default "IPS Repository", for the build system, that all packages will be published to, resides at the root directory of the cloned "OmniOS Extra IPS Repository". The root directory of this default "IPS Repository" is named tmp.repo.

Installing the package

It is a good idea to install the package, to see the full process of the build system.

First, the build systems "IPS Repository" needs to be imported on the local system. This can be done by importing the tmp.repo as a secondary "OmniOS Extra IPS Repository". This can be achieved from the helloworld directory as follows:

# pkg set-publisher -g ../../tmp.repo local.omnios

Next, all that is needed, is to install the package:

# pkg install helloworld

To verfify the complete build process, run the helloworld program.

$ helloworld
Hello, World!

`./build.sh` options

To gain more control over the build procedure, many options have been added to the build.sh script. The following table displays these options:

Option	Argument	Description
./build.sh -a	ARCH	build 32/64 bit only, or both (default: both)
./build.sh -b		batch mode (exit on errors without asking)
./build.sh -c		use 'ccache' to speed up (re-)compilation
./build.sh -d	DEPVER	specify an extra dependency version (no default)
./build.sh -D		collect package diff output in batch mode
./build.sh -f	FLAVOR	build a specific package flavor
./build.sh -h		print this help text
./build.sh -i		autoinstall mode (install build deps)
./build.sh -l		skip pkglint check
./build.sh -L		skip hardlink target check
./build.sh -p		output all commands to the screen as well as log file
./build.sh -P		re-base patches on latest source
./build.sh -r	REPO	specify the IPS repo to use (default: file:///omnios-extra/tmp.repo/)
./build.sh -t		skip test suite
./build.sh -s		skip checksum comparison
./build.sh -x		download and extract source only
./build.sh -xx		as -x but also apply patches

Now is a good time to try out some of these options whilst building the helloworld package.

Uninstall and remove the `helloworld` package from the default "IPS Repository"

To uninstall the helloworld package and also remove the package from the "IPS Repository", issue the following commands from the helloworld build directory:

# pkg uninstall helloworld
# pkgrepo -s ../../tmp.repo remove helloworld

Conclusion

This concludes the introductory section. Next, much finer details of the "OmniOS Extra Build System" will be explored.

The "OmniOS Extra Build System"

The "OmniOS Extra Build System" is a framework designed as a convenient and standardised manner to build IPS Packages for OmniOS. It is highly recommended to read Packaging and Delivering Software with the Image Packaging System, to fully understand the finer details of the "OmniOS Extra Build System".

The main engine behind the "OmniOS Extra Build System" is the lib/functions.sh file. In this section, a best effort has been made to describe in detail the workings of the build system, however, if certains details have not been described sufficiently, it is advised to look at the code of lib/functions.sh, as well as Packaging and Delivering Software with the Image Packaging System, to fill in the necessary gaps.

Package naming conventions
Structure of an OmniOS package
The local.mog and lib/mog/global-transforms.mog files
Build and run dependencies
Configure directives
Make directives
Linker directives
Using your own functions in build.sh
Creating patches
SMF manifests
Providing messages at installation
Making the source available to the build environment
Managing licences
Adding package information to the build system
The build system's default "IPS Repository"

Package naming conventions

Package catagories

Search doc/baseline for a list of package categories, to determine which best fits the package that is being built.

Installation directories

Simple packages

Simple packages that do not include sub-directories such as include, lib & share can be installed directly into the root /opt/ooce directory.

This can be done by omiting the --prefix= option in the CONFIGURE_OPTS directive of build.sh.

More complex packages

Other more complex packages should be installed under the /opt/ooce/ directory. For example the PostgreSQL server is installed to /opt/ooce/pgsql-12

Multiple Versions

Further, the version number of the package should not be included unless more than one version of the software is being packaged. The naming scheme with application-x.y symbolises that the application install directories contain a major version number. Meaning bugfix only releases would replace a previous version, but a new major version would NOT necessarily replace an existing one. Meaning you could install multiple versions of perl of python or even some obscure tool in parallel. The mediated symlinks allow you to choose the default version, but the other versions would still be accessible by using a direct path.

Structure of an OmniOS package

The "OmniOS Extra Repository" contains prime quality packages to enhance your OmniOS system. The packages make full use of SMF and adhere to the /opt package structure. There is a separate "OmniOS Extra Repository" for each release of OmniOS.

Directory structure

Purpose	Location
immutable package files	/opt/ooce/package(-x.y)
configuration files	/etc/opt/ooce/package(-x.y)
log files	/var/log/ooce/package(-x.y)
other var files	/var/opt/ooce/package(-x.y)
mediated symlinks provide access to binaries	/opt/ooce/bin
mediated symlinks provide access to manual pages	/opt/ooce/share/man*

Build framework

Refer to doc/framework for an overview of the build framework, descriptions of the various variables discussed below, and the functions and hooks which are available.

The `local.mog` and `lib/mog/global-transforms.mog` files

`local.mog`

The local.mog file is a way to transform package manifests programatically. This allows you to transform the contents of the package in reliable and repeatable ways. IPS uses pkgmogrify to achieve these changes.

In the local.mog file it is possible to change ownership and permissions on files, drop certain files from a package, make sure certain files do not get overwritten with newer versions. It also allows the creation of users and groups and even to adjust system services when a package has this requirement.

From the build.sh you can pass variables to local.mog with the following directive:

XFORM_ARGS="
    -DOPREFIX=${OPREFIX#/}
    -DPREFIX=${PREFIX#/}
    -DPROG=$PROG
    -DVER=$VER
"

This allows local.mog to read in these variables, and later in the build proccess, for pkgmogrify to make transformations upon them.

An example of transformations possible are as follows:

group groupname=$(PROG) gid=86
user ftpuser=false username=gitea uid=86 group=$(PROG) \
    gcos-field="Gitea - git with a cup of tea" \
    home-dir=/var/$(PREFIX) password=NP

<transform path=etc/$(PREFIX) -> set owner $(PROG)>
<transform path=etc/$(PREFIX) -> set group $(PROG)>
<transform file path=etc/$(PREFIX) -> set mode 0600>
<transform file path=etc/$(PREFIX) -> set preserve true>

<transform dir path=var/$(PREFIX) -> set owner $(PROG)>
<transform dir path=var/$(PREFIX) -> set group $(PROG)>

<transform dir path=var/$(PREFIX)/data -> set mode 0700>

<transform dir path=var/log/$(PREFIX) -> set owner $(PROG)>
<transform dir path=var/log/$(PREFIX) -> set group $(PROG)>

All these directives will be processed via the pkgmogrify utility.

The first is of particular interest as it creates a new user and group for the system.

Following this, is mainly setting ownership and permissions on files.

However of note, the line with set preserve true tells the build system not to overwrite files in the corresponding directory. In this case, old files will be left untouched and new files will be added with the prefix .new

It is beyond the scope of this document to describe in full detail the workings of how pkgmogify deals with the local.mog file, therefore it is recommended to read in detail Chapter 8 of Packaging and Delivering Software with the Image Packaging System, to best take advantage of the local.mog file.

`lib/mog/global-transforms.mog`

The "Omnios Build System" will automatically apply a number of transformations to a package being created via the lib/mog/global-transforms.mog file. It is recommended to study this file to appreciate, which changes are being made.

Build and run dependencies

Build Dependencies

Insert the following into build.sh to define the necessary programs to complete the build process.

BUILD_DEPENDS_IPS+="
    ooce/package/name1
    ooce/package/name2
    ooce/package/name3...
"

Anything from the base install or the meta packages extra-build-tools & omnios-build should not need to be included.

Optional Build Dependencies

If a package dependency is required to build the package but is not necessary to install the package, this can be dropped when the software is packaged, via a final.mog.

Include the package as normal in BUILD_DEPENDS_IPS directive and then use the following in the build.sh:

make_package local.mog final.mog

Also, include a final.mog file in the base of the package directory, with contents similar to below:

# Remove the automatically detected 'require' dependencies.
# Optional dependencies have already been explicitly added.
<transform depend type=require fmri=.*(?:mariadb|postgresql) -> drop>

For an example see here.

Run dependencies

Almost all run dependencies should be auto-detected. It's better to let this happen than to hard code it. If it is absolutely necessary to define run dependencies, the directive that is placed in build.sh is as follow:

RUN_DEPENDS_IPS+="
    ooce/package/name1
    ooce/package/name2
    ooce/package/name3...
"

Configure directives

Default configure flags are set in the lib/config.sh file. These may be overridden or appended to, with the CONFIGURE_OPTS directive. An example follows:

CONFIGURE_OPTS+="
    --prefix=$PREFIX
    --sysconfdir=/etc$PREFIX
    --localstatedir=/var$PREFIX
    --with-lockfile=/var$PREFIX/run/$PROG.lock
    --with-logfile=/var/log$PREFIX/$PROG.log
    --enable-openssl
"

These will be applied to the CONFIGURE_CMD for both 32 and 64 bit builds.

Architecture independent configure flags may also be set with the CONFIGURE_OPTS[i386] and CONFIGURE_OPTS[amd64] directives.

Make directives

Make directives may also be set and overridden in build.sh. Follows are possible use cases:

Supplying arguments to make:

MAKE_INSTALL_ARGS="
    COMMAND_OPTS=
    INSTALL_OPTS=
"

Determining make targets:

MAKE_INSTALL_TARGET="
    install
    install-commandmode
    install-config
"

Like the CONFIGURE_OPTS directive, these apply to both 32 and 64 bit builds.

Architecture independent configure flags may also be set with the MAKE_INSTALL_XXXXXX_32 and MAKE_INSTALL_XXXXXX_64 directives.

lib/functions.sh can provide a working example of how these directives are applied.

Linker directives

CFLAGS/LDFLAGS directives may also be set in build.sh. Follows are possible use cases:

CFLAGS+=" -O3 -I$OPREFIX/include -I/usr/include/gssapi"
CXXFLAGS[i386]+=" $CFLAGS ${CFLAGS[i386]} -R$OPREFIX/lib"
CXXFLAGS[amd64]+=" $CFLAGS ${CFLAGS[amd64]} -R$OPREFIX/lib/amd64"
LDFLAGS[i386]+=" -L$OPREFIX/lib -R$OPREFIX/lib"
LDFLAGS[amd64]+=" -L$OPREFIX/lib/amd64 -R$OPREFIX/lib/amd64"

Like the CONFIGURE_OPTS directive, the directives without the architecture prefix, apply to both 32 and 64 bit builds.

Architecture independent configure flags have also been set in the above example with the XXFLAGS[i386] and XXFLAGS[amd64] directives.

lib/functions.sh can provide a working example of how these directives are applied.

Using your own functions in `build.sh`

Sometimes it is not possible for the build system to cater for all events, when building a package. However, within build.sh, it is possible to create functions to deal with situations as they arise.

For example, when building a package that has no ./configure or make processes, it is possible to override the main build function as follows:

build() {
    logcmd $MKDIR -p $DESTDIR/$PREFIX/nagios/nrdp || logerr "mkdir"
    logcmd $CP -r $TMPDIR/$BUILDDIR/server/* $DESTDIR/$PREFIX/nagios/nrdp \
        || logerr "cp -r server failed"
}

In the above example, the package being built is from PHP source code. There is no ./configure or make processes and the contents can simply be copied into the $DESTDIR and then packaged by the build system.

This is a case of overriding a function, however it is also possible to create any functions that are necessary and place them in the right order amongst the "build functions" of the build.sh file.

The best source for discovering more about using your own functions, is to browse the build.sh of other packages.

Creating patches

Patches directory and contents

If it is neccessary to supply patches for the build to complete, these go in the sub-directory patches of the build/package-name directory.

Generally, one patch should be created for each functional change.. The following command should be sufficient to create a patch.

$ gdiff -wpruN '--exclude=*.orig' a~/ a/ > description-of-patch.patch

The patching may take place in the build/package-name/tmp directory, however the final patches must be transferred to the patches directory.

The filename of the patch should then be echo'd into a file named series, that resides in the patches directory. The file series, is used by the build system to apply the patches that are listed in this file. This is done in the order of the patches listed, so care must be taken, to list patches in order, as necessary for the build to complete,

$ echo description-of-patch.patch >> series

Re-basing patches to ensure the correct format

To ensure the patches are in the standard format for the build system, it is advised to run an automatic re-base. This can be achieved with the following command:

./build.sh -Pxx
...
Checking for patches in patches/ (in order to re-base them)
Re-basing patches
--- Applied patch Makefile.patch
Checking for patches in patches/ (in order to apply them)
Applying patches
--- Applied patch Makefile.patch
Time: ooce/application/package-name - 0h0m4s

The output from the command demonstrates that the patches have been re-based correctly.

SMF manifests

The "Service Management Facility" (SMF) replaces init.d scripts in OmniOS (and other illumos based distributions). SMF creates a unified model for services and service management.

If it is neccessary to include an SMF manifest with the package, the associated Manifest & Method files should be placed in the files sub-directory of the build/package-name directory.

It is preferably, however not always possible, that only a Manifest file should be included.

Once the associated SMF files have been placed in the files sub-directory, the build.sh can be instructed to process these files with the following directive:

install_smf application $PROG.xml application-$PROG

This should be placed after the "build function" declarations and before the make package declaration.

It is beyond the scope of this document to describe in full detail the workings of SMF, therefore it is highly recommended that you download and read "Management of Systems and Services with Solaris Service Management Facility".

Providing messages at installation

When providing a package which requires manual integration steps, it may be necessary to inform the end user of this situation. IPS has a facility to display a message during package installation to inform the end user of any important considerations that should be taken.

This is done by creating a text file and placing it in the files sub-directory of the build/package-name directory. An example text file that informs an end user, that they must read the installed IMPORTANT.txt file, would be similar to the following:

README

------------------
Installation Notes
------------------

For instructions on how to configure and integrate
this program with the system, please read
/opt/ooce/package-name/share/IMPORTANT.txt

------------------

Once this README file has been placed in the files sub-directory, the build.sh can be instructed to process this file with the following directive:

add_notes README

This should be placed after the "build function" declarations and before the make package declaration.

Making the source available to the build environment

Source tarballs via a mirror

Mirrors:

The omnios-extra build system has a mirror at https://mirrors.omnios.org/ that maintains current source tarballs and checksums. It uses these to build its packages. In the early stages of a build, this source tarball will not be available on the OmniOS mirror, and will be need to be made available for the build process.

This can be done by using the set_mirror directive in build.sh. For example the source tarball for "Apache httpd 2.4.43" is available at the mirror: https://downloads.apache.org/. Therefore the set_mirror directive should be as follows:

set_mirror "https://downloads.apache.org/"

Further in the build.sh file, the download_source directive should be as follows:

download_source $PROG $PROG $VER

Checksums:

The above will be sufficient if the accompanying sha256 checksum file is available in the same directory as the tarball.

If the checksum is not available, this can be included in the build.sh with the set_checksum directive. For example, had the "Apache httpd 2.4.43" checksum file not been available, the following set_checksum should be set:

set_checksum sha256 "a497652ab3fc81318cdc2a203090a999150d86461acff97c1065dc910fe10f43"

Source tarballs via GitHub

GitHub releases:

If the source tarball is on github, the following directive should be used:

set_mirror "$GITHUB/apache/$PROG/archive"

Further in the build.sh file, the download_source directive should be as follows:

download_source $VER

NOTE: Downloading from GitHub always seems to be a moving target. See the Exceptional cases regarding source tarballs section to help troubleshoot download_source problems.

Checksums:

GitHub does not supply checksums for downloaded archives, so this can be workd around with the following directive:

set_checksum "none"

Exceptional cases regarding source tarballs

Source tarball

Sometimes the source tarball is not in a standard format and the argument to the directive, download_source, will need to be edited accordingly.

Build Directory

Sometimes the tarball will extract to an un-expected directory. For example, sometimes a tarball named $PROG-$VER.tar.gz may extract to a directory named $PROG-$PROG-$VER.

In this case, use the BUILDDIR directive, as follows:

set_builddir "$PROG-$PROG-$VER"

Source Directory

Sometimes the source directory, where the configure script lies will not be where it is expected. For example, the configure script may not be in the root of the $PROG-VER/ directory, but instead in $PROG-VER/$PROG/.

In this case. the above set_builddir should also take care of this.

Managing licences

Bundling a licence with the package

All packages must be bundled with their respective licence. To add a licence to the package being built, the licence must be included in the local.mog file. This is generally always the last line of text in the local.mog file and appears as follows:

license COPYING license=GPLv3

How the build system determines the licence type

The utility, tools/licence, is used to determine the specific type of licence. To manually determine the licence that is bundled with the package run the following:

$ tools/licence build/package/tmp/path/to/LICENCE

This will return the licence type.

Licence definitions

Licence definitions can be viewed in doc/licences.

These definitions cover most open source licences.

If the licence is not detected, it is possible to use the SKIP_LICENCES directive, followed by the licence type, in build.sh. For example:

SKIP_LICENCES="Sleepycat"

When a package is released under various licences

In this case, it is possible to use the SKIP_LICENCES directive as follows:

SKIP_LICENCES=Various

The corresponding entry in the local.mog would appear similar as follows:

license LICENSE.adoc license=Various
license GPL-3.0.txt license=GPLv3

When no licence is supplied in the source tarball

It is possible to write a function in build.sh, to extract licence information in the source, if it is available.

An example function to extract the licence is as follows:

extract_licence() {
    logmsg "-- extracting licence"
    pushd $TMPDIR/$BUILDDIR > /dev/null
    sed '/^$/q' < $PROG.c > LICENCE
    popd > /dev/null
}

The licence may then be determined by the tools/licence utility.

When all else fails

As a last resort, you may consider modifying the licence definition pattern in doc/licences. You will need to let the maintainers explicitly aware of any changes to this file.

Adding package information to the build system

To keep the "OmniOS Build System" up-to-date, new packages need to be added to files in the doc/ directory. This is intuitive and can be achieved by simply browsing the files that need to be changed and then edit according, with details from the package that is being added.

The files that need editing are:

doc/baseline
doc/packages.md

The build system's default "IPS Repository"

The default "IPS Repository", for the build system, that all packages will be published to, resides at the root directory of the cloned "OmniOS Extra IPS Repository". The root directory of this default "IPS Repository" is named tmp.repo.

The build systems "IPS Repository" may be imported on the local system. This is done by importing the tmp.repo either as a secondary "OmniOS Extra IPS Repository" (but in that case the signature-policy must be set to ignore), or a local.omnios publisher can be added. This can be achieved as follows:

# cd /path/to/github/repos/omnios-extra/lib/
# cp site.sh.template site.sh

Change the line that defines PKGPUBLISHER :

diff site.sh site.sh.template
12c12
< PKGPUBLISHER=local.omnios
---
> #PKGPUBLISHER=extra.omnios

Then add the publisher :

# pkg set-publisher -g /path/to/github/repos/omnios-extra/tmp.repo local.omnios

With this set, the list of publishers should look similar to the following:

$ pkg publisher
PUBLISHER                   TYPE     STATUS P LOCATION
omnios              origin   online F https://pkg.omnios.org/bloody/core/
local.omnios        origin   online F file:///path/to/github/repos/omnios-extra/tmp.repo/
extra.omnios        origin   online F https://pkg.omnios.org/bloody/extra/

Tips for building specific types of packages

Building packages that share common elements
Tips for building libraries
Tips for Go packages
Tips for Perl packages
Tips for Python packages
Tips for Rust packages

Building packages that share common elements

When building a package for software that has many components, it may arise that the software should be split into separate packages. This presents a problem, when these packages share common elements, for example; the same user or directory structure.

The way to deal with this is to create a "Common Package" that the other packages can share.

A common package is simply a .mog file placed in the build directory of the main package that you are building. For example, the Nagios package, a .mog file named nagios-common.p5m is placed in the main build directory build/nagios. This file details the common elements shared with all the other Nagios packages.

For the build system to recognise this file, this Common Package should be added only to the doc/baseline file. This should not be added to doc/packages.md.

Examining the contents of nagios-common.p5m and other xxxxxx-common.p5m files should give you a better understanding to contributing these types of packages.

Tips for building libraries

Building libraries follows the same outline as building packages, however there are a few extra considerations that need to be applied.

Build for both 32 & 64 bit

Libraries are built for both 32 & 64 bit architectures. This just requires omiting the set_arch 64 directive from the standard build.sh file, that has been demonstrated in the "Create a build directory and its build files" section.

Drop 32 bit binaries

If a library installs 32 bit binaries, it is necessary to drop these before building the package. This can be set in the local.mog file, of the library being built.

This should be possible to achieve, with a statement in the local.mog file, similar to the following:

# Drop 32bit binaries
<transform path=$(PREFIX)/s?bin/i386 -> drop>

Adding library information to the build system

Similar to how information is added to doc/... files, when building a standard package, library packages need also to add information to the meta package extra-build-tools. Therefore the build/meta/extra-build-tools.p5m file will need editing.

The complete list of files that need editing are:

build/meta/extra-build-tools.p5m
doc/baseline
doc/packages.md

Tips for Go packages

Coming Soon! In the meantime, browse the build scripts of GO packages in the repository.

Tips for Perl packages

Coming Soon! In the meantime, browse the build scripts of Perl packages in the repository.

Tips for Python packages

Coming Soon! In the meantime, browse the build scripts of Python packages in the repository.

Tips for Rust packages

Coming Soon! In the meantime, browse the build scripts of Rust packages in the repository.

Submit your package to the "OmniOS Extra IPS Repository"

Final tasks before submitting a package

Make sure that the package has been added to doc/baseline
Make sure that the package has been added to doc/packages.md
If the package is a library, make sure that it has been added to build/meta/extra-build-tools.p5m

Create a "Pull Request" for the "OmniOS Extra IPS Repository"

Once work has been completed for a new package, the git branch will be needed to be pushed to the fork of the "OmniOS Extra IPS Repository" that was created in the first section.

The procedure to update the fork is as follows:

git add *
git status
git commit -m 'name of package and version number'
git push --set-upstream origin `git-branch`

After the initial commit of the git-branch has been uploaded, it is possible to omit the --set-upstream option from subsequent updates. This is demonstrated below:

git push origin `git-branch`

Viewing the new branch online at https://github.com, it is now possible to create a new pull request. To the right of the "Branch" menu, click "New pull request" to submit the new package to OmniOS.

Keeping updated with upstream omnios-extra

If there have been commits upstream on the original master, after cloning the fork, it is necessary to ensure that the local repository is up-to-date with the remote master. This is done by first updating the local repository that has been cloned from the fork, and then, updating the fork with the newly updated local repository.

Updating local repository with upstream remote

First determine if the upstream omniosorg/omnios-extra repository is set as a remote.

git remote -v

If the upstream ominosorg/omnios-extra repository is not set, add this with the following command:

git remote add upstream https://github.com/omniosorg/omnios-extra.git

Now confirm that the remote upstream ominosorg/omnios-extra repository is set.

git remote -v

To pull all the data from the remote into the local repository. Use the fetch and merge subcommands. Before doing this, check that the current branch is set to master.

git branch
git checkout master
git fetch upstream
git merge upstream/master

git fetch only downloads new data from a remote repository - but it doesn't integrate any of this new data into the working files.

git merge is where the fetched data is pulled into the working files.

After executing the above commands only the local repository will be up-to-date with the remote upstream omniosorg/omnios-extra repository.

Updating GitHub fork with local repository

Once the local repository is up-to-date, it is recommended to push this local repository to GitHub so that the fork of omniosorg/omnios-extra is also up-to-date.

git push origin master

OmniOS community support channels

Gitter: Connect to the web-based chat room on Gitter.
IRC: Join the #omnios channel on Libera.
Mailing list: general discussion and queries, please subscribe to the omnios-discuss mailing list.

Name		Name	Last commit message	Last commit date
Latest commit History 5,742 Commits
.github		.github
build		build
doc		doc
lib		lib
tools		tools
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md

License

omniosorg/omnios-extra

Folders and files

Latest commit

History

Repository files navigation

Building OmniOS Packages

Introduction

Prepare to build packages for OmniOS

The "OmniOS Extra Build System"

Tips for building specific types of packages

Submit your package to the "OmniOS Extra IPS Repository"

Getting Help

Prepare to build packages for OmniOS

Requirements

Create the build environment

Fork the "OmniOS Extra IPS Repository"

Create a local repository on the build system

Create a build directory and its build files

Create a git branch and a build directory

Create the build files

build.sh

local.mog

Build the helloworld package

Installing the package

./build.sh options

Uninstall and remove the helloworld package from the default "IPS Repository"

Conclusion

The "OmniOS Extra Build System"

Package naming conventions

Package catagories

Installation directories

Simple packages

More complex packages

Multiple Versions

Structure of an OmniOS package

Directory structure

Build framework

The local.mog and lib/mog/global-transforms.mog files

local.mog

lib/mog/global-transforms.mog

Build and run dependencies

Build Dependencies

Optional Build Dependencies

Run dependencies

Configure directives

Make directives

Supplying arguments to make:

Determining make targets:

Linker directives

Using your own functions in build.sh

Creating patches

Patches directory and contents

Re-basing patches to ensure the correct format

SMF manifests

Providing messages at installation

README

Making the source available to the build environment

Source tarballs via a mirror

Mirrors:

Checksums:

Source tarballs via GitHub

GitHub releases:

Checksums:

Exceptional cases regarding source tarballs

Source tarball

Build Directory

Source Directory

Managing licences

Bundling a licence with the package

How the build system determines the licence type

Licence definitions

When a package is released under various licences

When no licence is supplied in the source tarball

When all else fails

Adding package information to the build system

The build system's default "IPS Repository"

Tips for building specific types of packages

Building packages that share common elements

Tips for building libraries

Create a `git branch` and a build directory

`build.sh`

`local.mog`

Build the `helloworld` package

`./build.sh` options

Uninstall and remove the `helloworld` package from the default "IPS Repository"

The `local.mog` and `lib/mog/global-transforms.mog` files

`local.mog`

`lib/mog/global-transforms.mog`

Using your own functions in `build.sh`