Skip to end of metadata
Go to start of metadata

oi-build is OpenIndiana's primary build framework for post-oi_151 development. It is set to replace all existing consolidations, vastly simplifying how we build the operating system.

oi-build is also tied into our continuous integration platform. When an update is committed to the oi-build mercurial repository, an automated build is kicked off. This will then automatically publish the built package to the /experimental repo, or generate an email alert if the build failed (to be completed).

oi-build overview

oi-build is a fork of Oracle's userland-gate, which we have extended and added additional software to. The layout is very similar.

Inside oi-build is a directory called "components", under which lives a directory for each software package. Inside each of these software package directories is a main Makefile, as well as one or more .p5m IPS manifest files, and there may also be license files and patches.

The Makefile essentially contains a "build recipe". To build a piece of software, you simply cd into the directory of the software, and type "make TARGET", where TARGET can be one of:

  • prep : Download, extract and patch the software archive
  • build : Build the software
  • install : Install the software into the prototype directory
  • sample-manifest : Create a sample manifest file in the build directory
  • publish : Publish the software to the local userland IPS repo

For more details about writing Makefiles for userland, see userland Makefile targets and variables

Before adding new packages to illumos-userland...

Before considering adding a new package to oi-build, please check first whether someone else is working on the package by checking the issue tracker.

  • If you don't find anyone already working on a port, please register your effort by opening an issue.
  • If you wish to update an existing port, look at the log for the component Makefile ("hg log Makefile") and make sure you either contact the person who last updated the Makefile or include them on notifications for the issue by ticking their name.

This will ensure efforts aren't duplicated and help to ensure sanity and comity amongst project members.

Setting up your build environment

We strongly recommend building packages inside a fresh local zone set up exclusively for building. A good example howto on creating a build-zone can be found in the CrossBow instructions, see Building in zones.

Some suggestions about build environment (dataset layouts, etc.) can also be found in the illumos wiki: How to build illumos (note however that compilers required for the core OS may be different than those acceptable for userland software).

Ensuring your system is up to date

oi-build requires that your system be updated with the latest software from the pkg.openindiana.org/experimental repository.

The procedure to do this is as follows:

The first line adds the experimental repo to your package publisher list, the second line sets it as the primary publisher, and the third line allows packages from the experimental repo to replace those installed from the openindiana.org repo. The last line updates your system with the newer packages.

Note: If you are doing this in a zone and encounter an error from pkg about being unable to clone the current boot environment, you will need to update the zone from the global zone by doing:

/experimental

Note that the /experimental repo is under continuous development and may contain breakage. Thus we (as mentioned) strongly recommend building inside a dedicated development zone, rather than updating your main system.

 

Installing pre-requisites

First, lets install the required software list:

Changes on Sun Studio compilers

Oracle just moved the Studio Compiler. Now you need to login to access "Oracle Solaris Studio 12.3" they can be found at

http://www.oracle.com/technetwork/server-storage/solarisstudio/downloads/index.html

The following steps are needed to get it running:

Downloading oi-build and preparing for first use

See the illumos wiki instructions How to build illumos for optional suggestions about build environment (dedicated ZFS dataset layouts, etc.)

Check out the repository (subdirectory oi-build must not pre-exist):

Now we will run the setup stage, which will prepare some tools, and create an IPS pkg5 repository for first use under the i386/build directory:

Important: Checking your environment

Make the check-environment target to check your environment is set up correctly:

This will report back any issues.

Adding the local repository to your publisher list

You will now be able to pkg install the software you have built and published via oi-build.

Optional: Running a local pkg server for installation on other zones/hosts

If you would like to use your oi-build repository on other zones or hosts, you can run a pkg server:

On other hosts, you can then specify http://hostname:10000 instead of the file:// address above.

See the illumos wiki instructions How to build illumos for optional suggestions about running a pkg server instance as an SMF service.

Ready to build and install your first package

Simply descend into the oi-build/components/SOFTWARE directory (where SOFTWARE is the name of the bit of software you wish to build):

Contributing changes back to oi-build

Preparing you changes for review

When you think your changes are ready for review you will need to generate a diff. The most common way to do this is "hg diff". It's recommended that you explain the implications of your changeset if it's not immediately obvious, and how you've tested it.

Committing changes

If you changeset has had either "2 thumbs up and 3 days open for review" or "4 thumbs up" then you are now ready to push you changes to the repo. Add and commit all files for your new component using:

Commit messages must follow this format:

When committing changes on behalf of someone else the commit message remains the same but you must pass the committer's name to hg commit.

Labels:
  1. Mar 09, 2012

    are the patched versions of Sun Studio required for building illumos-userland at this time?
    should i use SunStudio12u1-SunOS-x86-tar-ML.tar.bz2 instead of sunstudio12-patched-ii-2009Sep-sol-x86.tar.bz2 and sunstudio12u1-patched-ii-2010Feb-sol-x86.tar.gz?
    thx

    1. May 05, 2012

      Yup those would be fine, but we're hoping to switch to gcc as the primary with Sun Studio 12.3 as an optional compiler.

  2. Apr 22, 2012

    Shouldn't webrev be used to generate the diffs for public review?

    1. May 05, 2012

      You can if you'd prefer, but webrev is an illumos-gate thing. We're trying to keep the barriers to entry here as low as possible so new contributors can get started quickly and easily. Most people these days are familiar with github and bitbucket and those style of changesets.