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/spec_file_format.rst | 137 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 docs/source/spec_file_format.rst (limited to 'docs/source/spec_file_format.rst') diff --git a/docs/source/spec_file_format.rst b/docs/source/spec_file_format.rst new file mode 100644 index 0000000..8491ef1 --- /dev/null +++ b/docs/source/spec_file_format.rst @@ -0,0 +1,137 @@ +SPEC File Format +**************** + +Keywords +======== + +* **name** - The name of the package +* **repackage** - Change name of package +* **version** - Version of package +* **release** - Release number of package +* **maintainer** - Name and email address of current package maintainer + +* **group** - Name of group the package belongs to +* **upstream_url** - URL to package in repository +* **source_url** - URL to original source package +* **description** - Full description of package +* **summary** - Brief description of package +* **classification** - opensolaris package classification format [1]_ +* **arch** - Destined architecture of the package +* **license** - License of the package + +Directives +========== + +.. note:: + All commands issued in a directive block are processed by Bourne-Again Shell, + except for *%transforms* + +.. note:: + Directives must be closed with the **%end** tag + +%prep +----- + +Set of commands to be executed *before building*; +such as applying patches to source code in the $BUILD directory, changing +pre-configuration data, etc. + +Example:: + + %prep + # Apply various patches + patch -i $SOURCES/$name-$version-some_fixes.patch + + # Change execution path of all scripts + find $BUILD -type f -name "*.py" -exec sed -i -e 's|\!#/usr/local|\!#/usr/bin|g' {} \; + + %end + +%build +------ + +Set of commands to be executed as part of the build process; +such as running any configuration scripts, and compiling your application(s). + +Example:: + + %build + ./configure --prefix=/opt --with-pymalloc + make -j2 + + %end + +%install +-------- + +Set of commands to executed as part of the installation process; +such as moving data to the build installation directory after being compiled. + +Example:: + %install + make install DESTDIR=$BUILDPROTO + %end + + +%transforms +----------- + +A syntatical reference is available from `oracle's transforms documentation `_ + + +Available shell expansion variables +=================================== + +* **BUILDROOT** - ipsutils/BUILDROOT/[package] +* **BUILDPROTO** - ipsutils/BUILDROOT/[package]/root +* **BUILD** - ipsutils/BUILD/[package] +* **SOURCES** - ipsutils/SOURCES/[package source_url basename] +* **PKGS** - ipsutils/PKGS/[package] +* **SPKGS** - ipsutils/SPKGS/[package] + +.. note:: + Macro expansion for ipsutils is in its infancy. If you are familiar with macro expansion + in RPM's SPEC implementation; there is nothing even remotely close to it here. This will be + addressed in the future. + +SPEC file example +================= + +This is a generic example of an IPS spec file + +:: + + name: ipsutils + version: 0.6.0 + release: 1 + maintainer: "Joseph Hunkeler " + upstream_url: http://localhost/$name-$version.tar.gz + source_url: http://localhost/$name-$version.tar.gz + description: "Python IPS library" + summary: "A python based IPS library" + group: developer + classification: "org.opensolaris.category.2008:Development/Distribution Tools" + arch: i386 + license: GPL + + %prep + %end + + %build + python setup.py build + + %end + + %install + python setup.py install --root=$BUILDPROTO --prefix=/opt/ipsutils + %end + + %transforms + edit group bin sys> + %end + + +Footnotes +========= + +.. [1] `IPS package classifications `_ \ No newline at end of file -- cgit From e71ec0a7f4784f3cc4d365a6212609fdebf5de33 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Mon, 1 Jul 2013 12:20:50 -0400 Subject: Add transmogrify note --- docs/source/spec_file_format.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/source/spec_file_format.rst') diff --git a/docs/source/spec_file_format.rst b/docs/source/spec_file_format.rst index 8491ef1..213dd6f 100644 --- a/docs/source/spec_file_format.rst +++ b/docs/source/spec_file_format.rst @@ -78,6 +78,10 @@ Example:: A syntatical reference is available from `oracle's transforms documentation `_ +.. note:: + + ``ipsbuild`` will automatically transmogrify directory permissions that do not match overlapping system directories. + Available shell expansion variables =================================== -- cgit From a09ab72b4238492abebb7059a636f6f1f0818a03 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Mon, 1 Jul 2013 17:49:02 -0400 Subject: fix install script example --- docs/source/spec_file_format.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/source/spec_file_format.rst') diff --git a/docs/source/spec_file_format.rst b/docs/source/spec_file_format.rst index 213dd6f..b175299 100644 --- a/docs/source/spec_file_format.rst +++ b/docs/source/spec_file_format.rst @@ -68,6 +68,7 @@ Set of commands to executed as part of the installation process; such as moving data to the build installation directory after being compiled. Example:: + %install make install DESTDIR=$BUILDPROTO %end -- cgit From 554f10293f5a233933f1be915fdc190efd7ab8e9 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Thu, 11 Jul 2013 10:13:30 -0400 Subject: Add badpath keyword --- docs/source/spec_file_format.rst | 113 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 113 insertions(+) (limited to 'docs/source/spec_file_format.rst') diff --git a/docs/source/spec_file_format.rst b/docs/source/spec_file_format.rst index b175299..e2debd7 100644 --- a/docs/source/spec_file_format.rst +++ b/docs/source/spec_file_format.rst @@ -13,12 +13,122 @@ Keywords * **group** - Name of group the package belongs to * **upstream_url** - URL to package in repository * **source_url** - URL to original source package +* **badpath** - Name of extracted top-level directory * **description** - Full description of package * **summary** - Brief description of package * **classification** - opensolaris package classification format [1]_ * **arch** - Destined architecture of the package * **license** - License of the package +Keywords, in-depth +================== + +.. _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. + +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`` + +badpath +------- + +Some developers may package their source code with a top-level directory name that differs +from what is written to disk. + +Example: ``gtar tfvz tkdiff-4.2.tar.gz`` :: + + -rw-r--r-- dorothyr/users 5910 2011-11-26 21:08 tkdiff-unix/CHANGELOG.txt + -rw-r--r-- dorothyr/users 18092 2011-11-26 21:08 tkdiff-unix/LICENSE.txt + -rwxr-xr-x dorothyr/users 1084 2011-11-26 21:08 tkdiff-unix/README.txt + -rwxr-xr-x dorothyr/users 341372 2011-11-26 21:08 tkdiff-unix/tkdiff + +The *name* of the package is **tkdiff-4.2** and the directory structure is **tkdiff-unix**. +This scenario will cause ipsbuild to fail unless the ``badpath`` keyword is used to circumvent the issue. + +Example: :: + + badpath: tkdiff-unix + +arch +---- + +There are only two architectures available: + +- i386 +- sparc + +.. note: + + There is no automatic architecture detection in IPS. + +classification +-------------- + +.. _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 +----------- + +A long detailed description of your package. + + Directives ========== @@ -94,6 +204,9 @@ Available shell expansion variables * **PKGS** - ipsutils/PKGS/[package] * **SPKGS** - ipsutils/SPKGS/[package] +.. note:: + All available *keywords* are expandable, too. + .. note:: Macro expansion for ipsutils is in its infancy. If you are familiar with macro expansion in RPM's SPEC implementation; there is nothing even remotely close to it here. This will be -- cgit From fa6fd989c19f693b04bd593621406b4b80df0177 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Thu, 11 Jul 2013 17:17:08 -0400 Subject: Fixup: repackas should have been repackage. The former was deprecated. --- docs/source/spec_file_format.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) (limited to 'docs/source/spec_file_format.rst') diff --git a/docs/source/spec_file_format.rst b/docs/source/spec_file_format.rst index e2debd7..524c96e 100644 --- a/docs/source/spec_file_format.rst +++ b/docs/source/spec_file_format.rst @@ -9,7 +9,6 @@ Keywords * **version** - Version of package * **release** - Release number of package * **maintainer** - Name and email address of current package maintainer - * **group** - Name of group the package belongs to * **upstream_url** - URL to package in repository * **source_url** - URL to original source package @@ -34,10 +33,10 @@ 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 --------- +repackage +--------- -To create an IPS package under a different name use the ``repackas`` keyword. In this case, ``Python`` +To create an IPS package under a different name use the ``repackage`` 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. -- cgit From 0fab5ada6c0dc1020f2bd044557c7c416d892b2e Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Thu, 11 Jul 2013 17:40:51 -0400 Subject: Removed deprecated double-quotes from example SPEC --- docs/source/spec_file_format.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/source/spec_file_format.rst') diff --git a/docs/source/spec_file_format.rst b/docs/source/spec_file_format.rst index 524c96e..b03af7c 100644 --- a/docs/source/spec_file_format.rst +++ b/docs/source/spec_file_format.rst @@ -221,13 +221,13 @@ This is a generic example of an IPS spec file name: ipsutils version: 0.6.0 release: 1 - maintainer: "Joseph Hunkeler " + maintainer: Joseph Hunkeler upstream_url: http://localhost/$name-$version.tar.gz source_url: http://localhost/$name-$version.tar.gz - description: "Python IPS library" - summary: "A python based IPS library" + description: Python IPS library + summary: A python based IPS library group: developer - classification: "org.opensolaris.category.2008:Development/Distribution Tools" + classification: org.opensolaris.category.2008:Development/Distribution Tools arch: i386 license: GPL -- cgit