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/code.rst | 16 +++ docs/source/conf.py | 246 +++++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 24 ++++ docs/source/spec_file_format.rst | 137 ++++++++++++++++++++++ docs/source/tutorial.rst | 9 ++ 5 files changed, 432 insertions(+) create mode 100644 docs/source/code.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst create mode 100644 docs/source/spec_file_format.rst create mode 100644 docs/source/tutorial.rst (limited to 'docs/source') diff --git a/docs/source/code.rst b/docs/source/code.rst new file mode 100644 index 0000000..9fcb413 --- /dev/null +++ b/docs/source/code.rst @@ -0,0 +1,16 @@ +Code Reference +************** + +.. automodule:: ipsutils + :members: + +.. autoclass:: ipsutils.build.Build + :members: __init__ + +.. autoclass:: ipsutils.config.Config + :members: __init__ + +.. autoclass:: ipsutils.env.Environment + :members: __init__ + + diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..fa07dd3 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,246 @@ +# -*- coding: utf-8 -*- +# +# ipsutils documentation build configuration file, created by +# sphinx-quickstart on Mon Jun 17 14:58:59 2013. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +sys.path.insert(0, os.path.abspath('..')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'ipsutils' +copyright = u'2013, Joseph Hunkeler' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.6.0' +# The full version, including alpha/beta/rc tags. +release = '0.6.0' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'ipsutilsdoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'ipsutils.tex', u'ipsutils Documentation', + u'Joseph Hunkeler', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'ipsutils', u'ipsutils Documentation', + [u'Joseph Hunkeler'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------------ + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'ipsutils', u'ipsutils Documentation', + u'Joseph Hunkeler', 'ipsutils', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..d2f01d3 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,24 @@ +.. ipsutils documentation master file, created by + sphinx-quickstart on Mon Jun 17 14:58:59 2013. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to ipsutils's documentation! +==================================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + spec_file_format + tutorial + code + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + 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 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') 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') 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 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') 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 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') 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 119b1ffd5e14895f089030c498149cdb78568a02 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Mon, 1 Jul 2013 12:21:39 -0400 Subject: Change theme --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/conf.py b/docs/source/conf.py index fa07dd3..b8f6f8c 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -91,7 +91,7 @@ pygments_style = 'sphinx' # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'default' +html_theme = 'sphinxdoc' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the -- 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') 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 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') 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 d8384b2a19ea7e05606f67e4c77f8b706aed4331 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Thu, 11 Jul 2013 10:08:22 -0400 Subject: Initial commit --- docs/source/installation.rst | 72 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 docs/source/installation.rst (limited to 'docs/source') diff --git a/docs/source/installation.rst b/docs/source/installation.rst new file mode 100644 index 0000000..9de19d4 --- /dev/null +++ b/docs/source/installation.rst @@ -0,0 +1,72 @@ +Installation +************ + +Requirements +============ + +* Solaris >= 11.0 +* Python == 2.7 + + +Getting ipsutils +================ + +Clone ipsutils git repository +----------------------------- + +:: + + git clone http://bitbucket.org/jhunkeler/ipsutils.git + cd ipsutils + + +Generate ipsutils build environment +----------------------------------- + +:: + + PYTHONPATH=. ./ipsbuild-setuptree.py + + +Create source distribution +-------------------------- + +:: + + python2.7 setup.py build sdist + + +Copy resulting tarball to ipsutils build SOURCES directory +---------------------------------------------------------- + +:: + + cp dist/ipsutils-VERSION.tar.gz ~/ipsutils/SOURCES + + +Build ipsutils +============== + +:: + + PYTHONPATH=. ./ipsbuild.py ipsbuild.ips + + +Publish ipsutils to your local repository +----------------------------------------- + +:: + + pkgsend publish \ + -s /your/repo \ + -d ~/ipsutils/PKGS/ipsutils-VERSION/root \ + ~/ipsutils/PKGS/ipsutils-VERSION/ipsutils-VERSION.res + + +Install ipsutils from your local repository +------------------------------------------- + +:: + + pkg install ipsutils + -- cgit From 82aa50dc09487652d49fcd0c16916cc36eaae0e4 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Thu, 11 Jul 2013 10:09:37 -0400 Subject: Initial commit --- docs/source/utility_reference.rst | 58 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 docs/source/utility_reference.rst (limited to 'docs/source') diff --git a/docs/source/utility_reference.rst b/docs/source/utility_reference.rst new file mode 100644 index 0000000..f7e6139 --- /dev/null +++ b/docs/source/utility_reference.rst @@ -0,0 +1,58 @@ +Utility reference +================= + +ipsbuild +-------- + +:: + + ipsbuild.py [-h] [--version] [--verbose] [--lint] [spec [spec ...]] + + Build Solaris 11 packages from .ips spec files + + positional arguments: + spec An ipsutils spec file + + optional arguments: + -h, --help show this help message and exit + --version Show version information + --verbose Increased verbosity + --lint Enables deep packaging checks + + +ipsutils-newspec +---------------- + +:: + + usage: ipsutils-newspec.py [-h] [spec [spec ...]] + + Generates a fresh .ips spec file + + positional arguments: + spec name of package(s) + + optional arguments: + -h, --help show this help message and exit + + +ipsutils-sanity +--------------- + +:: + + usage: ipsutils-sanity.py [-h] pkgpath + + Installation viability checking + + positional arguments: + pkgpath Path to package (e.g ~/ipsbuild/PKGS/{PACKAGE}) + + optional arguments: + -h, --help show this help message and exit + + +ipsbuild-setuptree +------------------ + +*No usage information* -- cgit From 20ca15759634a9ab676ad6593d870150cd2bc945 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Thu, 11 Jul 2013 10:10:51 -0400 Subject: Add link to installation procedure --- docs/source/index.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'docs/source') diff --git a/docs/source/index.rst b/docs/source/index.rst index d2f01d3..79946fe 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -9,11 +9,13 @@ Welcome to ipsutils's documentation! Contents: .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - spec_file_format + installation tutorial - code + spec_file_format + utility_reference + Indices and tables ================== -- 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') 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 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') 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 12219eb65889c77b972d705d42d7f019ad73d826 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Thu, 11 Jul 2013 17:09:27 -0400 Subject: Initial commit --- docs/source/publishing.rst | 92 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 docs/source/publishing.rst (limited to 'docs/source') diff --git a/docs/source/publishing.rst b/docs/source/publishing.rst new file mode 100644 index 0000000..9adc53e --- /dev/null +++ b/docs/source/publishing.rst @@ -0,0 +1,92 @@ +Publishing +========== + +.. warning:: + + IPS has no security measures in place to prevent others from pushing malicious + packages upstream. To combat this problem you will need to adhere to two + simple rules: + + 1. A repository marked read-write *must not* be accessible from the internet. + 2. Packages may only be pushed by trusted systems (restricted by a firewall) + +If you have not created a custom repository, please refer to Oracle's +`pkgrepo `_ +documentation and `this tutorial `_ +before continuing. + +Which repository do I want? +--------------------------- + +.. warning:: + + *Never* commit custom packages to the standard ``solaris`` repository. Doing + so may break the entire IPS backend and cause future package upgrades to + fail. + +Executing ``pkg publisher`` will display a list of available repositories: :: + + PUBLISHER TYPE STATUS P LOCATION + solaris origin online F http://localhost/solaris + solarisstudio origin online F http://localhost/solarisstudio + myrepo origin online F http://localhost/myrepo:10000 + + +``myrepo`` and its *LOCATION* ``http://localhost/myrepo:10000`` + + +Sending +------- + +Using ``pkgsend``, commit an ipsutils package to your custom IPS repository: :: + + cd ~/ipsutils/PKGS/mypackage + pkgsend -g http://localhost/myrepo:10000 -d root mypackage.res + +Alternatively, you may use absolute paths: :: + + pkgsend -g http://localhost/myrepo:10000 \ + -d ~/ipsutils/PKGS/mypackage/root \ + ~/ipsutils/PKGS/mypackage/mypackage.res + +.. note:: + + A repository's **read-only** flag must be set to **False** for HTTP/HTTPS + transactions to be successfull. + + +Refresh +------- + +Before your package will be available (via HTTP) the repository must be refreshed. +On the IPS repository server, execute: :: + + pkgrepo refresh -s /path/to/repository + + +Testing +------- + +In order to test installing your package, you will need to become root. +Despite IPS providing a ``--dry-run`` argument, it will still write to files in +located in ``/var/pkg``. + +Method One +~~~~~~~~~~ + +As root, execute: :: + + ipsutils-sanity.py ~/ipsutils/PKGS/mypackage + +.. note:: + + This method does not require a remote repository. It will create a local + repository in ``/tmp`` then delete it when it finishes. Good to use if you + are afraid to clutter up your existing repository. + +Method Two +~~~~~~~~~~ + +As root, execute: :: + + pkg install --dry-run mypackage -- cgit From 2d60a82b0f218bcf552c0c1973eadba8995fc21a Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Thu, 11 Jul 2013 17:16:13 -0400 Subject: Add publishing --- docs/source/index.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/source') diff --git a/docs/source/index.rst b/docs/source/index.rst index 79946fe..b9c98c3 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -15,6 +15,7 @@ Contents: tutorial spec_file_format utility_reference + publishing Indices and tables -- 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') 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 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') 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 From b1d37d960fa432dd15d9562ecd9202ad9e81cbfb Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Thu, 11 Jul 2013 17:19:47 -0400 Subject: Finally removed code.rst... (for now) --- docs/source/code.rst | 16 ---------------- 1 file changed, 16 deletions(-) delete mode 100644 docs/source/code.rst (limited to 'docs/source') diff --git a/docs/source/code.rst b/docs/source/code.rst deleted file mode 100644 index 9fcb413..0000000 --- a/docs/source/code.rst +++ /dev/null @@ -1,16 +0,0 @@ -Code Reference -************** - -.. automodule:: ipsutils - :members: - -.. autoclass:: ipsutils.build.Build - :members: __init__ - -.. autoclass:: ipsutils.config.Config - :members: __init__ - -.. autoclass:: ipsutils.env.Environment - :members: __init__ - - -- 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') 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 From d380572437a4bef8e0cf8883fb90eff9324d29b4 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Mon, 15 Jul 2013 10:05:25 -0400 Subject: Move publishing section higher in the list --- docs/source/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/index.rst b/docs/source/index.rst index b9c98c3..39ea2b0 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -13,9 +13,9 @@ Contents: installation tutorial + publishing spec_file_format utility_reference - publishing Indices and tables -- cgit From 72da90730347eaaf81c038144189d7add698bc5b Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Mon, 15 Jul 2013 10:06:33 -0400 Subject: Fixup: missing example case --- docs/source/publishing.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/source') diff --git a/docs/source/publishing.rst b/docs/source/publishing.rst index 9adc53e..fe4b410 100644 --- a/docs/source/publishing.rst +++ b/docs/source/publishing.rst @@ -32,6 +32,7 @@ Executing ``pkg publisher`` will display a list of available repositories: :: myrepo origin online F http://localhost/myrepo:10000 +In this case you will want to use: ``myrepo`` and its *LOCATION* ``http://localhost/myrepo:10000`` -- cgit