Hierarchy

Description

List of the top-level directories:

DirectoryContent
archivesSource tarballs downloaded for building components.
componentsHierarchy of directories containing packaging recipes.
docDocumentation of the build system.
make-rulesMakefile rules used by components.
templatesTemplates of component Makefile for different types of build toolchains.
toolsScripts used by the build system.
transformsDefault rules used for the generation of IPS packages.

Categories

All components were originally laid out in one-level but are being reorganized by categories.

Whenever a component is added or updated, it should be placed under the directory indicates by the Categories layout.

Meta-packages

These components do not deliver any file content but define groups of software or logic to manage installation/removal/deprecation of packages.

They are all located within the directory 'components/meta-packages'.

Component structure

A component is comprised of a set of files providing rules for:

  1. fetching source code,
  2. configuring, building, and installing software,
  3. preparing package content and generating one (or more) package.

The resulting package(s) are then published to a local repository.

Files

NameContent
MakefileRecipe for configuring, building, and installing software for the component.
*.licenseDocument containing all the licenses applicable to the packages.
*.p5mOne or more manifests describing package metadata and content.
historyRules for package renaming and deprecation.
manifests/Manifests generated automatically by the sample-manifest target.
patches/Patches: indexed and name with a .patch extension.
test/Test results for reproducible builds.

 

Makefile targets

TargetFunctionWhen to use it?
clobberClean up the directory content and remove archives. 
cleanClean up the directory. 
env-prepInstall dependencies listed in the REQUIRED_PACKAGES variable. 
prepFetch the source archives unpack, and apply patches. 
buildConfigure and builds the software. 
installInstall to the prototype directory. 

sample-manifest

Generate sample manifest from the content found in the prototype directory. 

pre-publish

Run the publication stage without sending packages to the local repository. 
publishRun the publication stage and publish to the local repository. 
REQUIRED_PACKAGESGenerate a list of runtime dependencies detected: build dependencies may need to be added automatically 

 

Testing

The testing framework can be used to make build reproducible and ensure that no regression is introduced when components are updated.

Support for the 'test' target should be ideally added to any component at creation or at update if it is not the case.

Makefile variables 'COMPONENT_TEST_*' affecting the execution of the test suite are declared in shared-macros.mk: most of these variables need not be changed.

Adding support for tests is covered in 3. Common Tasks: Reproducible builds and test suites

Recommendations

A list of recommendations for maintainers is listed at Best Practices.

IPS manifests

Manifest generation

Package actions

Content

ActionDefinitionUsage
file  
dir  
link  
hardlink  
user  
group  
driver  

Metadata

ActionDefinitionUsage
set  
depend  
license  
signature  

 

Transforms

Transforms are mainly used to set default attributes to files like ownership and permissions.

They are defined in oi-userland's transforms directory.

Examples

Set mode for binary executables:

<transform file path=usr/lib/$(MACH64)/e.+/utils/.+ -> default mode 0555>

 

Variants and facets

Incorporations

Linting

Package repositories

On-disk repositories

Remote repositories

Working with a pkg(5) server