Before working on any fix or feature, rebase you local 'oi/hipster' branch and create a new branch:
Let us consider that component 'library/foo' should be updated to latest version.
These instructions provide a generic overview of the process for updating a component: oi-userland best practices and tasks should be reviewed as well for a description of current tasks and framework modifications.
The component directory should be cleaned up prior to any modification to the files:
Before building an existing component, its dependencies should be installed on the system:
Packages listed in the Makefile variable REQUIRED_PACKAGES will be installed or updated.
Please note that the automatic procedure for generating REQUIRED_PACKAGES only detects runtime dependencies: build dependencies like system headers may be added manually.
If you find a missing dependency, add it to REQUIRED_PACKAGES and commit the change.
Update the following variables in the component Makefile:
If the checksum hash is not provided, use the output of the checksum verification stage in 'gmake prep'.
Download and patch the package:
Existing patches may not apply correctly against the new version and need be updated, in which case 'gmake prep' will fail to complete.
The component will be built, installed, and a new manifest copied to 'manifest/sample-manifest.p5m': review the difference and update the component manifest accordingly.
To check if the publication of the component can complete without actually publishing the package to the local repository, execute:
If 'REQUIRED_PACKAGES' is not provided at the end of the component Makefile, the list of dependencies should be generated:
If a test suite is provided by the package, run:
If test results have changed or simply testing was not set up for the component, follow the instructions for testing a component.
Anytime a component is updated, it is recommended to review existing security issues and opened issues which may affect illumos.
When the component publishes correctly, verify that the process completes as expected:
The component may re-publish the second time but should not the third time.
Adding patches to components for fixing bugs or security issues *without* updating to a newer version consists of a few simple steps:
Example: list dependencies
After choosing where to place the new component based on its category, create the component directoy and copy a sample Makefiles from the template directory.
The template to copy depends on the build system used by the software to be packaged.
Before any further work on the component, fill-in all the fields required for the package metadata.
A default manifest is generated using the target sample-manifest and created in manifest/sample-manifest.p5m
Copy the sample manifest in the component directory as $(COMPONENT_NAME).p5m, or if necessary split it in different manifests.
This manifest can be modified in several ways, for example:
The list of dependencies is automatically generated using the target REQUIRED_PACKAGES.
A list of detected runtime dependencies will be appended to the Makefile.
Example: Minimum dependency for a library.
The procedure does not detect build or test dependencies, nor may find dependencies that are only text files.
They should be added manually in a separate list before the runtime dependencies.
Example: Test dependencies were added to ensure reproducibility of the test results
In some particular cases dependency resolution may fails for some files contained in the manifest: it is then possible to bypass or override the dependency mechanism.
Refer to the IPS documentation for more details.
If the component is to be delivered as part of a software group, it should be added to the corresponding metapackage.
Metapackage components are listed under the meta-packages directory.
Add the newly created component to the manifest, for example in xorg-video.p5m:
xorg-video-vboxvideo was added to the xorg-video metapackage with a "require" dependency.
Finally, increment the component revision in the Makefile since the package content was modified.
If a package has no consumer and may cause security issues or unjustified maintenance burden it should be made obsolete in oi-userland.
Such decision should be motivated and discussed amongst developers.
First list all the known package FMRIs provided by the component:
The following rules for deprecation apply:
|Latest FMRI||Increment the COMPONENT_REVISION|
|Renamed FMRI||Set the branch version to the current BRANCH_ID|
Nomenclature: FMRI versioning
The base BRANCHID is set with COMPONENT_REVISION = 0, then increment as the component is republished.
Add the component FMRIs to the file components/meta-packages/history/history, listed in alphabetical order.
Example: clang-34 deprecation
1. The last component FMRI found in the repository was:
The FMRI to add to the history file show have an incremented COMPONENT_REVISION from 5 to 6.
2. The component contains the history file 'components/developer/clang-34/history':
The current BRANCH_ID is 2017.0.0.0 since the latest published package is email@example.com,5.11-2017.0.0.5.
The list to add to the history file is:
Remove the directory containing the component:
Whenever one (or more) package FMRI changes the component needs to take into account of the change.
To be able to resolve version constraints across renames the package management system needs to generate rename actions: this way the package can be tracked as the same even if the name changed.
The rename actions are generated via a 'history' file which contains mappings from the old name to the new name.
In the same commit as the package FMRI rename, add a file name 'history' or modify it if it exists,
For each package devliered by the component and affected by the change, add a line containing the full FMRI of the package (including the version string) and the new package FMRI (without version), separated by a space.
Example: When updating the component jq to version 1.5 a typo was discovered. The following line maps what the full FMRI would have been without renaming to the new package FMRI.
Test suites can be easily run for any component supporting them, and the test results compared with reference output.
Even when results are not reproducible, it is always a good idea to add support for this target in components so that regressions can be caught.
After the component is built and installed test suites can be run using 'gmake test' if the 'test' target is declared in the component Makefile.
Example: tests for 32-bit and 64-bit versions
The environment of the test suite can be changed with the variable 'COMPONENT_TEST_ENV'.
If a master result file exists in the component test directory, the output produced by the test run is compared against master test results.
The default directory for master test results is 'test' as defined in the variable 'COMPONENT_TEST_RESULTS_DIR'.
Default names for the master files are defined in the variable 'COMPONENT_TEST_MASTER' as:
and correspond to 32-bit and 64-bit builds respectively.
The first time a master result file is added to the component, an empty file should be created prior to running 'gmake test' to trigger the comparison stage.
Example: initial creation of a master results file for a 32-bit build
The comparison will fail as the master results file is empty: the actual test output should be copied to the test result directory (do not forget to commit the newly created file).
If the results are architecture independent, the variable may be set to:
Test results may be processed to retain relevant machine-independent output only.
Transforms of the output are controlled by two variables:
Only test results are retained:
Timestamps should be removed:
The components updated or modified may affect the system in a critical way, possibly putting services in a non-functioning state.
In order to avoid damaging your current installation, the recommended practice is to create a new Boot Environment (BE) then install the packages to be tested in this new environment.
The following commands should be run with administrative rights (using sudo) or by a user with "Software Installation" profile (using pfexec).
Choose a name for the new BE which corresponds to the nature of the testing, say "testX".
Note the mounting point of the BE, to substitute to /path/to/be in the following commands.
Most pkg commands can be applied to a mounted BE using the option -R and the path to the BE mountpoint:
If the package to be to tested is constrained by an incorporation, the version lock should be removed, or the incorporation can simply be uninstalled in the created BE.
For example this step is required for packages listed in the userland-incorporation:
If only a few packages are version locked, the constraint can be removed on an individual basis.
For example, removing the version lock for xeyes:
Two common cases of package testing are described below.
If the packages are delivered from a repository as a bulk update, the test repository should be added as preferred and the main repository set as non-sticky to allow cross-publisher updates.
For example, installing new bits from the xorg-testing repository requires:
If the packages to be tested are published to your local repository, they can be installed to the new BE by providing the full path to the local repository and the list of full packages FMRIs including version and timestamp.
When the packages are installed, the test BE can be activated to make it default at the next reboot:
As soon as the component you added or modified is ready:
Optionally you can select one or two reviewers familiar with the component or the software category to speed-up the review process.
By default all the commands work with the local list of installed packages: to query information from remote publishers the option '-r' shoud be specified.
Listing the publishers configured on the system:
Example: list of publisher on a system with both official OpenIndiana repositories and local repositories used by the developer.
The official repositories are placed in higher priority and all repositories are set non-sticky so that:
If a publisher is set as sticky updating any package from this publisher to another package provided by a different publisher is forbidden: in short, no cross-publisher update is allowed.
Print information about a given package:
Example: print information on libjpeg-turbo (the full FMRI need not be passed if there is not ambiguity with the package name)
List packages depending on the current package:
Example: packages depending on libjpeg-turbo (the full FMRI is needed).
A list of recommendation is updated at Best Practices for oi-userland