diff options
Diffstat (limited to 'docs/source/tutorial.rst')
| -rw-r--r-- | docs/source/tutorial.rst | 299 |
1 files changed, 299 insertions, 0 deletions
diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst new file mode 100644 index 0000000..5c186cc --- /dev/null +++ b/docs/source/tutorial.rst @@ -0,0 +1,299 @@ +Tutorial +******** + +.. warning:: + + Never build IPS packages as root! + +Please review the `SPEC File Format <spec_file_format.html>`_ before continuing. + + +Creating an IPS package from scratch +==================================== + +In this tutorial we will create an IPS package from the ground up. +We will build ``ccache`` (`<http://ccache.samba.org>`_), +because of its lightweight code footprint, and easy installation +method. + + +Generate ipsutils build tree +---------------------------- + + +ipsutils provides a script to automatically create your build environment:: + + ipsbuild-setuptree.py + +Example output:: + + Creating directory: /home/acct/ipsbuild + Creating directory: /home/acct/ipsbuild/BUILDROOT + Creating directory: /home/acct/ipsbuild/BUILD + Creating directory: /home/acct/ipsbuild/SPECS + Creating directory: /home/acct/ipsbuild/SOURCES + Creating directory: /home/acct/ipsbuild/PKGS + Creating directory: /home/acct/ipsbuild/SPKGS + + +Download the source +------------------- +.. _here: http://ccache.samba.org/download.html + +Get the latest version from here_. + +**-OR-** + +Download ``ccache`` directly with ``wget``:: + + wget -P ~/ipsbuild/SOURCES http://samba.org/ftp/ccache/ccache-3.1.9.tar.bz2 + +.. note:: + + ``wget`` may not installed by default. + To install it on Solaris 11 execute: + ``pkg install wget`` + + +Creating a SPEC file +-------------------- + +Writing an ipsutils SPEC file from scratch is a daunting task, +much like when working with RPM SPEC files. There is a utility, ``ipsutils-newspec`` +available to help. This creates all available keywords and directives so that you +may pick and choose which ones to fill out. + +:: + + # ipsutils-newspec ~/ipsutils/SPECS/ccache.ips + Generating '/home/acct/ipsutils/SPECS/ccache.ips' spec file + +Contents of generated file:: + + name: ccache + repackage: + version: + release: 1 + group: + summary: + license: + maintainer: + upstream_url: + source_url: + arch: + classification: + description: + + + %prep + + %end + + %build + + %end + + %install + + %end + + %transforms + + %end + +.. warning:: + + Keywords with no values specified will cause ipsbuild to fail + +.. warning:: + + Keywords must contain a single space after the ':' character + + +Filling in the FMRI section +--------------------------- + +The FMRI section of your SPEC file should look something like the following: :: + + name: ccache + version: 3.1.9 + release: 1 + group: developer + summary: Cache system for GCC + license: GPL + maintainer: John Doe <john@example.com> + upstream_url: http://samba.org/ftp/ccache/$name-$version.tar.bz2 + source_url: $name-$version.tar.bz2 + arch: i386 + classification: org.opensolaris.category.2008:Development/C + description: ccache is a compiler cache. It speeds up recompilation by caching previous compilations. + + +Applying scripts +---------------- + +``ccache`` does not require any prep work to get running. +In practice, if we had a critial patch to apply, or configuration files to +modify, we would do so in the ``%prep`` section. + + +Build section +~~~~~~~~~~~~~ + +:: + + %build + + # Run autotools script + ./configure --prefix=/usr + + # Build the package + gmake -j2 + + %end + +Install section +~~~~~~~~~~~~~~~ + +:: + + %install + + gmake install DESTDIR=$BUILDPROTO + + %end + +.. warning:: + + Files copied to $BUILDPROTO will be incorporated into your package manifest + + +Applying transforms +------------------- + +IPS packing contains a bizarre technology named *transmogrification* that, in theory, +is a great idea. The ability to transform file names, permissions, paths all in +a single albeit long convoluted string directive. + +It is too cumbersome to modify a package manifest by hand every time you realize +there is something missing. The ``%transforms`` section is **not** a shell script. +Any text written to this section (except ``#`` comments) will be written directly +to the package manifest. + +Care must be taken to ensure the tranforms syntax is properly written, because like +most things in Oracle IPS, there is no error checking at runtime. Error checking +appears to be at-the-time, which makes writing IPS packages (successfully) a very +difficult experience. + +Syntax: [1]_ +``<transform {type} {{keyword}={value} ...} -> {action} {modifications...}>`` + +Example usage :: + + %transforms + <transform dir path=opt$ -> edit group bin sys> + %end + +This will change the group ownership of ``/opt`` from ``bin`` to ``sys``. +However, ipsutils does this for you automatically, making these calls no longer necessary. + +.. [1] Not confusing at all, right Oracle? + + +Putting it all together +----------------------- + +Your completed SPEC file, if you have been following along, should look similar to +the following: :: + + name: ccache + version: 3.1.9 + release: 1 + group: developer + summary: Cache system for GCC + license: GPL + maintainer: John Doe <john@example.com> + upstream_url: http://samba.org/ftp/ccache/$name-$version.tar.bz2 + source_url: $name-$version.tar.bz2 + arch: i386 + classification: org.opensolaris.category.2008:Development/C + description: ccache is a compiler cache. It speeds up recompilation by caching previous compilations. + + %build + + # Run autotools script + ./configure --prefix=/usr + + # Build the package + gmake -j2 + + %end + + %install + + gmake install DESTDIR=$BUILDPROTO + + %end + + +Building your package +--------------------- + +The simplest and fastest way to get started building your IPS package requires +nothing fancy. Execute ipsbuild and watch your build take flight. + +:: + + ipsbuild ccache.ips + +Example (truncated for brevity):: + + Summary of ccache + + name: ccache + + repackage: + + version: 3.1.9 + + release: 1 + + group: developer + + summary: Cache system for GCC + + license: GPL + + maintainer: John Doe <john@example.com> + + upstream_url: http://samba.org/ftp/ccache/ccache-3.1.9.tar.bz2 + + source_url: ccache-3.1.9.tar.bz2 + + arch: i386 + + classification: org.opensolaris.category.2008:Development/C + + description: ccache is a compiler cache. It speeds up recompilation by caching previous compilations. + + Running task: Unpack source + Detected archive with extension: .tar.bz2 + + Running task: Create build root + + Running task: Generate meta data + + Running task: prep + + Running task: build + configure: Configuring ccache + [...] + configure: creating ./config.status + config.status: creating Makefile + config.status: creating config.h + configure: now build ccache by running make + gcc -g -O2 -Wall -W -DHAVE_CONFIG_H -I. -I. -c -o main.o main.c + gcc -g -O2 -Wall -W -DHAVE_CONFIG_H -I. -I. -c -o ccache.o ccache.c + gcc -g -O2 -Wall -W -DHAVE_CONFIG_H -I. -I. -c -o mdfour.o mdfour.c + gcc -g -O2 -Wall -W -DHAVE_CONFIG_H -I. -I. -c -o hash.o hash.c + gcc -g -O2 -Wall -W -DHAVE_CONFIG_H -I. -I. -c -o execute.o execute.c + gcc -g -O2 -Wall -W -DHAVE_CONFIG_H -I. -I. -c -o util.o util.c + [...] + + Running task: install + /usr/bin/ginstall -c -d /home/acct/ipsbuild/BUILDROOT/ccache-3.1.9/root/usr/bin + /usr/bin/ginstall -c -m 755 ccache /home/acct/ipsbuild/BUILDROOT/ccache-3.1.9/root/usr/bin + /usr/bin/ginstall -c -d /home/acct/ipsbuild/BUILDROOT/ccache-3.1.9/root/usr/share/man/man1 + /usr/bin/ginstall -c -m 644 ./ccache.1 /home/acct/ipsbuild/BUILDROOT/ccache-3.1.9/root/usr/share/man/man1/ + + Running task: Generate file manifest + + Running task: Transmogrifying file manifest + + Running task: Automatic dependencies + + Running task: Dependency resolution + > Running internal task: Automatic permission alignment + Discovering directory entries in manifest... + Cross-referencing system paths... + Repairing permissions... + + Running task: Generate package + + Running task: Generate source package +
\ No newline at end of file |