diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | docs/Makefile | 153 | ||||
| -rw-r--r-- | docs/conf.py | 244 | ||||
| -rw-r--r-- | docs/index.rst | 22 | ||||
| -rw-r--r-- | docs/make.bat | 190 | ||||
| -rw-r--r-- | docs/source/conf.py | 246 | ||||
| -rw-r--r-- | docs/source/index.rst | 27 | ||||
| -rw-r--r-- | docs/source/installation.rst | 72 | ||||
| -rw-r--r-- | docs/source/publishing.rst | 93 | ||||
| -rw-r--r-- | docs/source/spec_file_format.rst | 254 | ||||
| -rw-r--r-- | docs/source/tutorial.rst | 299 | ||||
| -rw-r--r-- | docs/source/utility_reference.rst | 58 |
12 files changed, 1659 insertions, 0 deletions
@@ -1,3 +1,4 @@ +docs/build nbproject/* MANIFEST dist/* diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..fde201f --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,153 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make <target>' where <target> is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/ipsutils.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/ipsutils.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/ipsutils" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/ipsutils" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..2d7700b --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,244 @@ +# -*- coding: utf-8 -*- +# +# ipsutils documentation build configuration file, created by +# sphinx-quickstart on Fri Jun 14 10:22:35 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('../../')) +for path in sys.path: + print(path) + +# -- 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.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 = ['_build'] + +# 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 +# "<project> v<release> 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 <link> 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' diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..60336a9 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,22 @@ +.. ipsutils documentation master file, created by + sphinx-quickstart on Fri Jun 14 10:22:35 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: 3 + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..f1ba85a --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,190 @@ +@ECHO OFF + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set BUILDDIR=build +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source +set I18NSPHINXOPTS=%SPHINXOPTS% source +if NOT "%PAPER%" == "" ( + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% + set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% +) + +if "%1" == "" goto help + +if "%1" == "help" ( + :help + echo.Please use `make ^<target^>` where ^<target^> is one of + echo. html to make standalone HTML files + echo. dirhtml to make HTML files named index.html in directories + echo. singlehtml to make a single large HTML file + echo. pickle to make pickle files + echo. json to make JSON files + echo. htmlhelp to make HTML files and a HTML help project + echo. qthelp to make HTML files and a qthelp project + echo. devhelp to make HTML files and a Devhelp project + echo. epub to make an epub + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + echo. text to make text files + echo. man to make manual pages + echo. texinfo to make Texinfo files + echo. gettext to make PO message catalogs + echo. changes to make an overview over all changed/added/deprecated items + echo. linkcheck to check all external links for integrity + echo. doctest to run all doctests embedded in the documentation if enabled + goto end +) + +if "%1" == "clean" ( + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + del /q /s %BUILDDIR%\* + goto end +) + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "singlehtml" ( + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "htmlhelp" ( + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %BUILDDIR%/htmlhelp. + goto end +) + +if "%1" == "qthelp" ( + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %BUILDDIR%/qthelp, like this: + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\ipsutils.qhcp + echo.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\ipsutils.ghc + goto end +) + +if "%1" == "devhelp" ( + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. + goto end +) + +if "%1" == "epub" ( + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The epub file is in %BUILDDIR%/epub. + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "text" ( + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The text files are in %BUILDDIR%/text. + goto end +) + +if "%1" == "man" ( + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The manual pages are in %BUILDDIR%/man. + goto end +) + +if "%1" == "texinfo" ( + %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. + goto end +) + +if "%1" == "gettext" ( + %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The message catalogs are in %BUILDDIR%/locale. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + if errorlevel 1 exit /b 1 + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "linkcheck" ( + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck + if errorlevel 1 exit /b 1 + echo. + echo.Link check complete; look for any errors in the above output ^ +or in %BUILDDIR%/linkcheck/output.txt. + goto end +) + +if "%1" == "doctest" ( + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + if errorlevel 1 exit /b 1 + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +:end diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..b8f6f8c --- /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 = '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 +# 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 +# "<project> v<release> 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 <link> 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..39ea2b0 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,27 @@ +.. 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: 1 + + installation + tutorial + publishing + spec_file_format + utility_reference + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + 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 + diff --git a/docs/source/publishing.rst b/docs/source/publishing.rst new file mode 100644 index 0000000..fe4b410 --- /dev/null +++ b/docs/source/publishing.rst @@ -0,0 +1,93 @@ +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 <http://docs.oracle.com/cd/E23824_01/html/E21796/pkgrepo-1.html>`_ +documentation and `this tutorial <http://www.scalingbits.com/solaris/ips/configuration>`_ +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 + + +In this case you will want to use: +``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 diff --git a/docs/source/spec_file_format.rst b/docs/source/spec_file_format.rst new file mode 100644 index 0000000..b03af7c --- /dev/null +++ b/docs/source/spec_file_format.rst @@ -0,0 +1,254 @@ +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 +* **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``. + +repackage +--------- + +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. + +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 <john@example.com>`` + +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 +========== + +.. 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 <http://docs.oracle.com/cd/E26502_01/html/E21383/xformrules.html>`_ + +.. note:: + + ``ipsbuild`` will automatically transmogrify directory permissions that do not match overlapping system directories. + + +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:: + 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 + 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 <jhunk@stsci.edu> + 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 + <transform dir path=opt$ -> edit group bin sys> + %end + + +Footnotes +========= + +.. [1] `IPS package classifications <http://docs.oracle.com/cd/E26502_01/html/E21383/gentextid-3283.html#scrolltoc>`_
\ No newline at end of file diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst new file mode 100644 index 0000000..5c186cc --- /dev/null +++ b/docs/source/tutorial.rst @@ -0,0 +1,299 @@ +Tutorial +******** + +.. warning:: + + Never build IPS packages as root! + +Please review the `SPEC File Format <spec_file_format.html>`_ before continuing. + + +Creating an IPS package from scratch +==================================== + +In this tutorial we will create an IPS package from the ground up. +We will build ``ccache`` (`<http://ccache.samba.org>`_), +because of its lightweight code footprint, and easy installation +method. + + +Generate ipsutils build tree +---------------------------- + + +ipsutils provides a script to automatically create your build environment:: + + ipsbuild-setuptree.py + +Example output:: + + Creating directory: /home/acct/ipsbuild + Creating directory: /home/acct/ipsbuild/BUILDROOT + Creating directory: /home/acct/ipsbuild/BUILD + Creating directory: /home/acct/ipsbuild/SPECS + Creating directory: /home/acct/ipsbuild/SOURCES + Creating directory: /home/acct/ipsbuild/PKGS + Creating directory: /home/acct/ipsbuild/SPKGS + + +Download the source +------------------- +.. _here: http://ccache.samba.org/download.html + +Get the latest version from here_. + +**-OR-** + +Download ``ccache`` directly with ``wget``:: + + wget -P ~/ipsbuild/SOURCES http://samba.org/ftp/ccache/ccache-3.1.9.tar.bz2 + +.. note:: + + ``wget`` may not installed by default. + To install it on Solaris 11 execute: + ``pkg install wget`` + + +Creating a SPEC file +-------------------- + +Writing an ipsutils SPEC file from scratch is a daunting task, +much like when working with RPM SPEC files. There is a utility, ``ipsutils-newspec`` +available to help. This creates all available keywords and directives so that you +may pick and choose which ones to fill out. + +:: + + # ipsutils-newspec ~/ipsutils/SPECS/ccache.ips + Generating '/home/acct/ipsutils/SPECS/ccache.ips' spec file + +Contents of generated file:: + + name: ccache + repackage: + version: + release: 1 + group: + summary: + license: + maintainer: + upstream_url: + source_url: + arch: + classification: + description: + + + %prep + + %end + + %build + + %end + + %install + + %end + + %transforms + + %end + +.. warning:: + + Keywords with no values specified will cause ipsbuild to fail + +.. warning:: + + Keywords must contain a single space after the ':' character + + +Filling in the FMRI section +--------------------------- + +The FMRI section of your SPEC file should look something like the following: :: + + name: ccache + version: 3.1.9 + release: 1 + group: developer + summary: Cache system for GCC + license: GPL + maintainer: John Doe <john@example.com> + upstream_url: http://samba.org/ftp/ccache/$name-$version.tar.bz2 + source_url: $name-$version.tar.bz2 + arch: i386 + classification: org.opensolaris.category.2008:Development/C + description: ccache is a compiler cache. It speeds up recompilation by caching previous compilations. + + +Applying scripts +---------------- + +``ccache`` does not require any prep work to get running. +In practice, if we had a critial patch to apply, or configuration files to +modify, we would do so in the ``%prep`` section. + + +Build section +~~~~~~~~~~~~~ + +:: + + %build + + # Run autotools script + ./configure --prefix=/usr + + # Build the package + gmake -j2 + + %end + +Install section +~~~~~~~~~~~~~~~ + +:: + + %install + + gmake install DESTDIR=$BUILDPROTO + + %end + +.. warning:: + + Files copied to $BUILDPROTO will be incorporated into your package manifest + + +Applying transforms +------------------- + +IPS packing contains a bizarre technology named *transmogrification* that, in theory, +is a great idea. The ability to transform file names, permissions, paths all in +a single albeit long convoluted string directive. + +It is too cumbersome to modify a package manifest by hand every time you realize +there is something missing. The ``%transforms`` section is **not** a shell script. +Any text written to this section (except ``#`` comments) will be written directly +to the package manifest. + +Care must be taken to ensure the tranforms syntax is properly written, because like +most things in Oracle IPS, there is no error checking at runtime. Error checking +appears to be at-the-time, which makes writing IPS packages (successfully) a very +difficult experience. + +Syntax: [1]_ +``<transform {type} {{keyword}={value} ...} -> {action} {modifications...}>`` + +Example usage :: + + %transforms + <transform dir path=opt$ -> edit group bin sys> + %end + +This will change the group ownership of ``/opt`` from ``bin`` to ``sys``. +However, ipsutils does this for you automatically, making these calls no longer necessary. + +.. [1] Not confusing at all, right Oracle? + + +Putting it all together +----------------------- + +Your completed SPEC file, if you have been following along, should look similar to +the following: :: + + name: ccache + version: 3.1.9 + release: 1 + group: developer + summary: Cache system for GCC + license: GPL + maintainer: John Doe <john@example.com> + upstream_url: http://samba.org/ftp/ccache/$name-$version.tar.bz2 + source_url: $name-$version.tar.bz2 + arch: i386 + classification: org.opensolaris.category.2008:Development/C + description: ccache is a compiler cache. It speeds up recompilation by caching previous compilations. + + %build + + # Run autotools script + ./configure --prefix=/usr + + # Build the package + gmake -j2 + + %end + + %install + + gmake install DESTDIR=$BUILDPROTO + + %end + + +Building your package +--------------------- + +The simplest and fastest way to get started building your IPS package requires +nothing fancy. Execute ipsbuild and watch your build take flight. + +:: + + ipsbuild ccache.ips + +Example (truncated for brevity):: + + Summary of ccache + + name: ccache + + repackage: + + version: 3.1.9 + + release: 1 + + group: developer + + summary: Cache system for GCC + + license: GPL + + maintainer: John Doe <john@example.com> + + upstream_url: http://samba.org/ftp/ccache/ccache-3.1.9.tar.bz2 + + source_url: ccache-3.1.9.tar.bz2 + + arch: i386 + + classification: org.opensolaris.category.2008:Development/C + + description: ccache is a compiler cache. It speeds up recompilation by caching previous compilations. + + Running task: Unpack source + Detected archive with extension: .tar.bz2 + + Running task: Create build root + + Running task: Generate meta data + + Running task: prep + + Running task: build + configure: Configuring ccache + [...] + configure: creating ./config.status + config.status: creating Makefile + config.status: creating config.h + configure: now build ccache by running make + gcc -g -O2 -Wall -W -DHAVE_CONFIG_H -I. -I. -c -o main.o main.c + gcc -g -O2 -Wall -W -DHAVE_CONFIG_H -I. -I. -c -o ccache.o ccache.c + gcc -g -O2 -Wall -W -DHAVE_CONFIG_H -I. -I. -c -o mdfour.o mdfour.c + gcc -g -O2 -Wall -W -DHAVE_CONFIG_H -I. -I. -c -o hash.o hash.c + gcc -g -O2 -Wall -W -DHAVE_CONFIG_H -I. -I. -c -o execute.o execute.c + gcc -g -O2 -Wall -W -DHAVE_CONFIG_H -I. -I. -c -o util.o util.c + [...] + + Running task: install + /usr/bin/ginstall -c -d /home/acct/ipsbuild/BUILDROOT/ccache-3.1.9/root/usr/bin + /usr/bin/ginstall -c -m 755 ccache /home/acct/ipsbuild/BUILDROOT/ccache-3.1.9/root/usr/bin + /usr/bin/ginstall -c -d /home/acct/ipsbuild/BUILDROOT/ccache-3.1.9/root/usr/share/man/man1 + /usr/bin/ginstall -c -m 644 ./ccache.1 /home/acct/ipsbuild/BUILDROOT/ccache-3.1.9/root/usr/share/man/man1/ + + Running task: Generate file manifest + + Running task: Transmogrifying file manifest + + Running task: Automatic dependencies + + Running task: Dependency resolution + > Running internal task: Automatic permission alignment + Discovering directory entries in manifest... + Cross-referencing system paths... + Repairing permissions... + + Running task: Generate package + + Running task: Generate source package +
\ No newline at end of file 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* |