diff options
| -rw-r--r-- | docs/source/tutorial.rst | 300 |
1 files changed, 185 insertions, 115 deletions
diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst index ace6a11..8050656 100644 --- a/docs/source/tutorial.rst +++ b/docs/source/tutorial.rst @@ -27,13 +27,13 @@ ipsutils provides a script to automatically create your build environment:: Example output:: - Creating directory: /Users/jhunk/ipsbuild - Creating directory: /Users/jhunk/ipsbuild/BUILDROOT - Creating directory: /Users/jhunk/ipsbuild/BUILD - Creating directory: /Users/jhunk/ipsbuild/SPECS - Creating directory: /Users/jhunk/ipsbuild/SOURCES - Creating directory: /Users/jhunk/ipsbuild/PKGS - Creating directory: /Users/jhunk/ipsbuild/SPKGS + 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 @@ -65,8 +65,8 @@ may pick and choose which ones to fill out. :: - # ipsutils-newspec ~/ipsutils/ccache.ips - Generating '/home/user/ipsutils/ccache.ips' spec file + # ipsutils-newspec ~/ipsutils/SPECS/ccache.ips + Generating '/home/acct/ipsutils/SPECS/ccache.ips' spec file Contents of generated file:: @@ -75,14 +75,14 @@ Contents of generated file:: version: release: 1 group: - summary: "" + summary: license: - maintainer: "" + maintainer: upstream_url: source_url: arch: - classification: "" - description: "" + classification: + description: %prep @@ -101,152 +101,222 @@ Contents of generated file:: %end +.. warning:: + + Keywords with no values specified will cause ipsbuild to fail + +.. warning:: + + Keywords must contain a single space after the ':' character -What are these keywords you speak of? -------------------------------------- - -.. _FMRI: http://docs.oracle.com/cd/E26502_01/html/E21383/pkgterms.html#glubk - -Keywords in an ipsutils SPEC file refer to the data inserted into the FMRI_ section of a package manifest. - -name -~~~~ - -The ``name`` of the package should match the first part of the source package. -If source package is named ``ccache-x.y.z.tar.gz`` the ``name`` field should be set to ``ccache``. -In the case of Python, for example, they use a capital 'p' in the source package filename: ``Python-3.2.1.tar.gz``. - -repackas -~~~~~~~~ - -To create an IPS package under a different name use the ``repackas`` keyword. In this case, ``Python`` -can be repackaged as ``python3`` and all subsequent modules (numpy, scipy, etc) can be repackaged as -``python3-[module]`` to make administration easier. - -version -~~~~~~~ - -The version of the package is generally provided in the name of the source archive. - -release -~~~~~~~ -The ``release`` keyword allow you to apply patches to the IPS package without the need to change the version number. -For example, if a maintainer releases a bugfix, but it does not increment the version number, you may apply the -patch, increment the release number, and push the package to your repository. Clients will then receive the latest -bugfix without incrementing the package version. +Filling in the FMRI section +--------------------------- -group -~~~~~ +The FMRI section of your SPEC file should look something like the following: :: -``group`` defines a subclass of the IPS package classification system. + 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. -summary -~~~~~~~ -``summary`` is a very brief description of the package's functional purpose. +Applying scripts +---------------- -license -~~~~~~~ +``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. -The ``license`` describes the package's current license (e.g. ``GPL``, ``BSD``, ``MIT``, etc) -maintainer -~~~~~~~~~~ +Build section +~~~~~~~~~~~~~ -The package maintainer's full name and email. Use the format: ``John Doe <john@example.com>`` +:: + + %build + + # Run autotools script + ./configure --prefix=/usr + + # Build the package + gmake -j2 + + %end -upstream_url -~~~~~~~~~~~~ +Install section +~~~~~~~~~~~~~~~ -URL to the original source archive on the internet (or intranet). Example, ``http://www.example.com/package-1.0.0.tar.gz`` +:: + + %install + + gmake install DESTDIR=$BUILDPROTO + + %end + +.. warning:: + + Files copied to $BUILDPROTO will be incorporated into your package manifest -source_url -~~~~~~~~~~ + +Applying transforms +------------------- -Although ``upstream_url`` can be in URL format, it is not a requirement. Example, ``package-1.0.0.tar.gz`` or ``http://www.example.com/package-1.0.0.tar.gz`` +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. -arch -~~~~ +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. -There are only two architectures available: +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. -- i386 -- sparc +Syntax: [1]_ +``<transform {type} {{keyword}={value} ...} -> {action} {modifications...}>`` -.. note: +Example usage :: - There is no automatic architecture detection in IPS. + %transforms + <transform dir path=opt$ -> edit group bin sys> + %end -classification -~~~~~~~~~~~~~~ +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. -.. _classification: http://docs.oracle.com/cd/E26502_01/html/E21383/gentextid-3283.html#scrolltoc +.. [1] Not confusing at all, right Oracle? -For a list of package classifications please refer to the IPS package classification_ documentation. -description -~~~~~~~~~~~ +Putting it all together +----------------------- -A long detailed description of your package. - - -Filling in the FMRI section ---------------------------- - -The FMRI section of your SPEC file should look something like the following: :: +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" + summary: Cache system for GCC license: GPL - maintainer: "John Doe <john@example.com>" + 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 and detecting when the same compilation \ - is being done again. Supported languages are C, C++, Objective-C and \ - Objective-C++" + classification: org.opensolaris.category.2008:Development/C + description: ccache is a compiler cache. It speeds up recompilation by caching previous compilations. -Scripting ---------- + %build + + # Run autotools script + ./configure --prefix=/usr + + # Build the package + gmake -j2 + + %end + + %install + + gmake install DESTDIR=$BUILDPROTO + + %end -prep -~~~~ -A shell script that will *prepare* your package. Applying patches, adding -additional resources, and modifying any files necessary to build your package. +Building your package +--------------------- -build -~~~~~ +The simplest and fastest way to get started building your IPS package requires +nothing fancy. Execute ipsbuild and watch your build take flight. -A shell script that will *build* your package. Here you will execute configuration -scripts, process makefiles, etc. +:: -install -~~~~~~~ + 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 + -A shell script that will *install* your package. Don't forget to -always use ``DESTDIR=$BUILDPROTO`` when executing ``make install``. +Publishing +========== .. note:: - All files that will end up in your package manifest must be installed to ``$BUILDPROTO``. - -An example in context :: - - %build - ./configure --prefix=/usr - make -j2 - %end + If you have not setup a custom repository, please refer to Oracle's ``pkgrepo`` documentation + before continuing. + +Repository discovery +-------------------- - %install - make install DESTDIR=$BUILDPROTO - %end +TODO +Sending +------- +TODO +Verifying +--------- + +TODO
\ No newline at end of file |