From 2430333bf672848b98e58ee3730610db79ecdd75 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Wed, 19 Jun 2013 17:21:42 -0400 Subject: Add sphinx documentation, initital commit --- docs/source/tutorial.rst | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 docs/source/tutorial.rst (limited to 'docs/source/tutorial.rst') diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst new file mode 100644 index 0000000..f1de3d1 --- /dev/null +++ b/docs/source/tutorial.rst @@ -0,0 +1,9 @@ +Tutorial +******** + +.. SPEC File Format_: spec_file_format + +Creating an IPS package from scratch +==================================== + +Please take a few minutes to review `SPEC File Format `_ \ No newline at end of file -- cgit From d4a8095ed8b429bdb077c789ed7f378d68be2ad7 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Mon, 24 Jun 2013 17:35:07 -0400 Subject: Add download link(s) --- docs/source/tutorial.rst | 56 ++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 54 insertions(+), 2 deletions(-) (limited to 'docs/source/tutorial.rst') diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst index f1de3d1..6905c8a 100644 --- a/docs/source/tutorial.rst +++ b/docs/source/tutorial.rst @@ -1,9 +1,61 @@ Tutorial ******** -.. SPEC File Format_: spec_file_format +.. warning:: + + Never build IPS packages as root! + +Please review the `SPEC File Format `_ before continuing. + Creating an IPS package from scratch ==================================== -Please take a few minutes to review `SPEC File Format `_ \ No newline at end of file +In this tutorial we will create an IPS package from the ground up. +We will build **ccache** (``_), +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: /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 + + +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`` + + + + + + + -- cgit From fdd8ffcd39055ba686b8e927520b09e8361a0494 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Tue, 25 Jun 2013 17:08:19 -0400 Subject: Add spec generation --- docs/source/tutorial.rst | 52 ++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 48 insertions(+), 4 deletions(-) (limited to 'docs/source/tutorial.rst') diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst index 6905c8a..73148c1 100644 --- a/docs/source/tutorial.rst +++ b/docs/source/tutorial.rst @@ -12,7 +12,7 @@ Creating an IPS package from scratch ==================================== In this tutorial we will create an IPS package from the ground up. -We will build **ccache** (``_), +We will build ``ccache`` (``_), because of its lightweight code footprint, and easy installation method. @@ -42,19 +42,63 @@ Download the source Get the latest version from here_. -OR +**-OR-** -Download ccache directly with ``wget``:: +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: + ``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 feels like a daunting task, +much like when working with RPM SPEC files. There is a utility, ``ipsutils-newspec`` +available to help help + +:: + + # ipsutils-newspec ~/ipsutils/ccache.ips + Generating '/home/user/ipsutils/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 -- cgit From 3d860d90258428e411c1a8aebed716e51f974a39 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Mon, 1 Jul 2013 12:21:31 -0400 Subject: Add keyword explanation and beginning of howto section --- docs/source/tutorial.rst | 92 ++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 90 insertions(+), 2 deletions(-) (limited to 'docs/source/tutorial.rst') diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst index 73148c1..5a54b1f 100644 --- a/docs/source/tutorial.rst +++ b/docs/source/tutorial.rst @@ -58,9 +58,10 @@ Download ``ccache`` directly with ``wget``:: Creating a SPEC file -------------------- -Writing an ipsutils SPEC file from scratch feels like a daunting task, +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 help +available to help. This creates all available keywords and directives so that you +may pick and choose which ones to fill out. :: @@ -101,5 +102,92 @@ Contents of generated file:: %end +What are these keywords you speak of? +------------------------------------- +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. + +group +~~~~~ + +``group`` defines a subclass of the IPS package classification system. + +summary +~~~~~~~ + +``summary`` is a very brief description of the package's functional purpose. + +license +~~~~~~~ + +The ``license`` describes the package's current license (e.g. ``GPL``, ``BSD``, ``MIT``, etc) + +maintainer +~~~~~~~~~~ + +The package maintainer's full name and email. Use the format: ``John Doe `` + +upstream_url +~~~~~~~~~~~~ + +URL to the original source archive on the internet (or intranet). Example, ``http://www.example.com/package-1.0.0.tar.gz`` + +source_url +~~~~~~~~~~ + +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`` + +arch +~~~~ + +There are only two architectures available: + +- i386 +- sparc + +.. note: + + This keyword is mandatory. There is no automatic architecture detection in IPS. + +classification +~~~~~~~~~~~~~~ + +For a list of package classifications please refer to `this site `_. + +description +~~~~~~~~~~~ + +A long detailed description of your package. + + +Filling in the blanks +===================== + +yadda yadda \ No newline at end of file -- cgit From 874ff835627cd1dd14e75ce7b56e12edcde48e98 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Mon, 1 Jul 2013 17:49:22 -0400 Subject: General additions --- docs/source/tutorial.rst | 71 ++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 65 insertions(+), 6 deletions(-) (limited to 'docs/source/tutorial.rst') diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst index 5a54b1f..ace6a11 100644 --- a/docs/source/tutorial.rst +++ b/docs/source/tutorial.rst @@ -105,7 +105,9 @@ Contents of generated file:: What are these keywords you speak of? ------------------------------------- -Keywords in an ipsutils SPEC file refer to the data inserted into the *fmri* section of a package manifest. +.. _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 ~~~~ @@ -174,12 +176,14 @@ There are only two architectures available: .. note: - This keyword is mandatory. There is no automatic architecture detection in IPS. + There is no automatic architecture detection in IPS. classification ~~~~~~~~~~~~~~ -For a list of package classifications please refer to `this site `_. +.. _classification: http://docs.oracle.com/cd/E26502_01/html/E21383/gentextid-3283.html#scrolltoc + +For a list of package classifications please refer to the IPS package classification_ documentation. description ~~~~~~~~~~~ @@ -187,7 +191,62 @@ description A long detailed description of your package. -Filling in the blanks -===================== +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 " + 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++" + +Scripting +--------- + +prep +~~~~ + +A shell script that will *prepare* your package. Applying patches, adding +additional resources, and modifying any files necessary to build your package. + +build +~~~~~ + +A shell script that will *build* your package. Here you will execute configuration +scripts, process makefiles, etc. + +install +~~~~~~~ + +A shell script that will *install* your package. Don't forget to +always use ``DESTDIR=$BUILDPROTO`` when executing ``make install``. + +.. 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 + + %install + make install DESTDIR=$BUILDPROTO + %end + + -yadda yadda \ No newline at end of file -- cgit From ded6b26cdea3c216573431af11869daef0c6a175 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Thu, 11 Jul 2013 10:16:02 -0400 Subject: Many changes, removed double-quote dependency from SPEC, and beginning publishing procedure --- docs/source/tutorial.rst | 300 +++++++++++++++++++++++++++++------------------ 1 file changed, 185 insertions(+), 115 deletions(-) (limited to 'docs/source/tutorial.rst') 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 + 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 `` +:: + + %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]_ +`` {action} {modifications...}>`` -.. note: +Example usage :: - There is no automatic architecture detection in IPS. + %transforms + 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 " + maintainer: John Doe 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 + + 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 -- cgit From 45e72dec0bc3b146ce1c01e2951007bb90990652 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Thu, 11 Jul 2013 17:17:39 -0400 Subject: Remove Publishing section to its own file --- docs/source/tutorial.rst | 25 +------------------------ 1 file changed, 1 insertion(+), 24 deletions(-) (limited to 'docs/source/tutorial.rst') diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst index 8050656..5c186cc 100644 --- a/docs/source/tutorial.rst +++ b/docs/source/tutorial.rst @@ -296,27 +296,4 @@ Example (truncated for brevity):: Repairing permissions... + Running task: Generate package + Running task: Generate source package - - -Publishing -========== - -.. note:: - - If you have not setup a custom repository, please refer to Oracle's ``pkgrepo`` documentation - before continuing. - -Repository discovery --------------------- - -TODO - -Sending -------- - -TODO - -Verifying ---------- - -TODO \ No newline at end of file + \ No newline at end of file -- cgit