[llvm-commits] [zorg] r99503 - in /zorg/trunk/lnt: CHANGELOG.txt README.txt docs/ docs/Makefile docs/README.txt docs/_templates/ docs/_templates/index.html docs/_templates/indexsidebar.html docs/_templates/layout.html docs/changes.rst docs/conf.py docs/contents.rst docs/intro.rst docs/make.bat docs/modules/ docs/modules/testing.rst docs/tools.rst lnt/__init__.py lnt/formats/__init__.py lnt/lnttool/__init__.py lnt/lnttool/create.py lnt/lnttool/import_data.py lnt/testing/__init__.py lnt/util/ImportData.py
Daniel Dunbar
daniel at zuster.org
Thu Mar 25 00:59:41 PDT 2010
Author: ddunbar
Date: Thu Mar 25 02:59:41 2010
New Revision: 99503
URL: http://llvm.org/viewvc/llvm-project?rev=99503&view=rev
Log:
LNT: Add/update docs.
Added:
zorg/trunk/lnt/CHANGELOG.txt
zorg/trunk/lnt/docs/
zorg/trunk/lnt/docs/Makefile
zorg/trunk/lnt/docs/README.txt
zorg/trunk/lnt/docs/_templates/
zorg/trunk/lnt/docs/_templates/index.html
zorg/trunk/lnt/docs/_templates/indexsidebar.html
zorg/trunk/lnt/docs/_templates/layout.html
zorg/trunk/lnt/docs/changes.rst
zorg/trunk/lnt/docs/conf.py
zorg/trunk/lnt/docs/contents.rst
zorg/trunk/lnt/docs/intro.rst
zorg/trunk/lnt/docs/make.bat
zorg/trunk/lnt/docs/modules/
zorg/trunk/lnt/docs/modules/testing.rst
zorg/trunk/lnt/docs/tools.rst
Modified:
zorg/trunk/lnt/README.txt
zorg/trunk/lnt/lnt/__init__.py
zorg/trunk/lnt/lnt/formats/__init__.py
zorg/trunk/lnt/lnt/lnttool/__init__.py
zorg/trunk/lnt/lnt/lnttool/create.py
zorg/trunk/lnt/lnt/lnttool/import_data.py
zorg/trunk/lnt/lnt/testing/__init__.py
zorg/trunk/lnt/lnt/util/ImportData.py
Added: zorg/trunk/lnt/CHANGELOG.txt
URL: http://llvm.org/viewvc/llvm-project/zorg/trunk/lnt/CHANGELOG.txt?rev=99503&view=auto
==============================================================================
--- zorg/trunk/lnt/CHANGELOG.txt (added)
+++ zorg/trunk/lnt/CHANGELOG.txt Thu Mar 25 02:59:41 2010
@@ -0,0 +1,4 @@
+0.3.0 (not yet released)
+========================
+
+* Initial release.
Modified: zorg/trunk/lnt/README.txt
URL: http://llvm.org/viewvc/llvm-project/zorg/trunk/lnt/README.txt?rev=99503&r1=99502&r2=99503&view=diff
==============================================================================
--- zorg/trunk/lnt/README.txt (original)
+++ zorg/trunk/lnt/README.txt Thu Mar 25 02:59:41 2010
@@ -5,87 +5,16 @@
infrastructure. This is technically version "3.0" of the LLVM nightly test
architecture.
-LNT is written in Python and implements a WSGI web app on top of Quixote, along
-with utilities for submitting data via LLVM's NewNightlyTest.pl in conjunction
-with LLVM's test-suite repository.
-
The infrastructure has the following layout:
- $ROOT/lnt - Top-level source module
-
- $ROOT/lnt/import - Utilities for converting to the LNT plist format for test
- data, and for submitting plists to the server.
-
- $ROOT/lnt/viewer - The LNT web-app itself.
+ $ROOT/lnt - Top-level Python 'lnt' module
$ROOT/db - Database schema, utilities, and examples of the LNT plist format.
+ $ROOT/docs - Sphinx documentation for LNT.
+
$ROOT/tests - Tests for the infrastructure; they currently assume they are
running on a system with a live instance available at
'http://localhost/zorg/'.
-
-Installation Instructions
--------------------------
-
-External Dependencies: SQLAlchemy, Quixote, mod_wsgi, SQLite, MySQL (optional)
-
-Internal Dependencies: MooTools
-
-These are the rough steps to get a working LNT installation:
-
- 1. Install LNT:
-
- python setup.py install
-
- It is recommended that you install LNT into a virtualenv.
-
- 2. Create a new LNT installation:
-
- lnt create path/to/install-dir
-
- This will create the LNT configuration file, the default database, and a
- .wsgi wrapper to create the application. You can execute the generated app
- directly to run with the builtin web server, or use 'lnt runserver' with the
- path the config file.
-
- 3. Edit the generated 'lnt.cfg' file if necessary, for example to:
-
- a. Update the databases list.
-
- b. Update the zorgURL.
-
- c. Update the nt_emailer configuration.
-
- 4. Add the zorg.wsgi app to your Apache configuration. You should set also
- configure the WSGIDaemonProcess and WSGIProcessGroup variables if not
- already done.
-
- If running in a virtualenv you will need to configure that as well; see the
- `modwsgi wiki <http://code.google.com/p/modwsgi/wiki/VirtualEnvironments>`_.
-
-
-Development Instructions
-------------------------
-
-Developing LNT should be done under a virtualenv (most likely in 'develop'
-mode). Currently, the tests require:
-
- 1. 'lit', the LLVM test runner, is available.
-
- 2. The hosted application is live at http://localhost/perf/.
-
- 3. lnt/tests/lit.cfg should be modified to have the correct '%email_host' and
- '%email_to' substitutions.
-
-To run the tests, use, e.g.,
-
- lit -sv $ROOT/lnt/tests
-
-or
-
- lit -sv $ZORG_ROOT/test
-
-to run the zorg and LNT tests all at once.
-
-Note that currently the email test will actually send you email.
+For more information, see the web documentation, or docs/.
Added: zorg/trunk/lnt/docs/Makefile
URL: http://llvm.org/viewvc/llvm-project/zorg/trunk/lnt/docs/Makefile?rev=99503&view=auto
==============================================================================
--- zorg/trunk/lnt/docs/Makefile (added)
+++ zorg/trunk/lnt/docs/Makefile Thu Mar 25 02:59:41 2010
@@ -0,0 +1,120 @@
+# 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) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp epub latex changes linkcheck doctest
+
+all: html
+
+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 " 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/LNT.qhcp"
+ @echo "To view the help file:"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/LNT.qhc"
+
+devhelp:
+ $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) _build/devhelp
+ @echo
+ @echo "Build finished."
+ @echo "To view the help file:"
+ @echo "# mkdir -p $$HOME/.local/share/devhelp/LNT"
+ @echo "# ln -s _build/devhelp $$HOME/.local/share/devhelp/LNT"
+ @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 all-pdf' or \`make all-ps' in that directory to" \
+ "run these through (pdf)latex."
+
+latexpdf: latex
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex
+ @echo "Running LaTeX files through pdflatex..."
+ make -C _build/latex all-pdf
+ @echo "pdflatex finished; the PDF files are in _build/latex."
+
+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."
Added: zorg/trunk/lnt/docs/README.txt
URL: http://llvm.org/viewvc/llvm-project/zorg/trunk/lnt/docs/README.txt?rev=99503&view=auto
==============================================================================
--- zorg/trunk/lnt/docs/README.txt (added)
+++ zorg/trunk/lnt/docs/README.txt Thu Mar 25 02:59:41 2010
@@ -0,0 +1,7 @@
+ LNT Documentation
+==================
+
+The LNT documentation is written using the Sphinx documentation generator. It is
+currently tested with Sphinx 1.0dev.
+
+We currently use the 'nature' theme and a Beaker inspired structure.
Added: zorg/trunk/lnt/docs/_templates/index.html
URL: http://llvm.org/viewvc/llvm-project/zorg/trunk/lnt/docs/_templates/index.html?rev=99503&view=auto
==============================================================================
--- zorg/trunk/lnt/docs/_templates/index.html (added)
+++ zorg/trunk/lnt/docs/_templates/index.html Thu Mar 25 02:59:41 2010
@@ -0,0 +1,38 @@
+{% extends "layout.html" %}
+{% set title = 'LNT' %}
+{% block body %}
+<h1>LNT - LLVM Performance Tracking Software</h1>
+
+<p>
+ LNT is LLVM's performance tracking software. This is the web page for the LNT
+ software itself, the current online version of the server is available
+ at <a href="http://llvm.org/perf/">http://llvm.org/perf/</a>.
+</p>
+
+<h2>Documentation</h2>
+<table class="contentstable" align="center" style="margin-left: 30px">
+ <tr>
+ <td width="50%">
+ <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">
+ Contents</a><br/>
+ <span class="linkdescr">for a complete overview</span></p>
+ <p class="biglink"><a class="biglink" href="{{ pathto("search") }}">
+ Search page</a><br/>
+ <span class="linkdescr">search the documentation</span></p>
+ </td><td width="50%">
+ <p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">
+ General Index</a><br/>
+ <span class="linkdescr">all functions, classes, terms</span></p>
+ <p class="biglink"><a class="biglink" href="{{ pathto("modindex") }}">
+ Module Index</a><br/>
+ <span class="linkdescr">quick access to all documented modules</span></p>
+ </td></tr>
+</table>
+
+<h2>Source</h2>
+<p>LNT is available in the LLVM "zorg" SVN repository:
+ <tt>svn co
+ <a href="http://llvm.org/svn/llvm-project/zorg/trunk/lnt">
+ http://llvm.org/svn/llvm-project/zorg/trunk/lnt</a></tt>.</p>
+
+{% endblock %}
Added: zorg/trunk/lnt/docs/_templates/indexsidebar.html
URL: http://llvm.org/viewvc/llvm-project/zorg/trunk/lnt/docs/_templates/indexsidebar.html?rev=99503&view=auto
==============================================================================
--- zorg/trunk/lnt/docs/_templates/indexsidebar.html (added)
+++ zorg/trunk/lnt/docs/_templates/indexsidebar.html Thu Mar 25 02:59:41 2010
@@ -0,0 +1,18 @@
+<h3>Download</h3>
+<ul>
+ <li><a href="lnt-{{ version }}.tar.gz">
+ Current version: {{ version }}</a>.</li>
+</ul>
+
+<h3>Install</h3>
+<ul>
+ <li>Current release:<br>
+ <tt>easy_install lnt=={{ version }}</tt></li>
+ <li>Development release:<br>
+ <tt>easy_install lnt==dev</tt></li>
+</ul>
+
+<h3>Bugs</h3>
+
+<p>LNT bugs should be reported at the
+ LLVM <a href="http://llvm.org/bugs">Bugzilla</a>.</p>
Added: zorg/trunk/lnt/docs/_templates/layout.html
URL: http://llvm.org/viewvc/llvm-project/zorg/trunk/lnt/docs/_templates/layout.html?rev=99503&view=auto
==============================================================================
--- zorg/trunk/lnt/docs/_templates/layout.html (added)
+++ zorg/trunk/lnt/docs/_templates/layout.html Thu Mar 25 02:59:41 2010
@@ -0,0 +1,13 @@
+{% extends "!layout.html" %}
+
+{% block extrahead %}
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+{% endblock %}
+
+{% block rootrellink %}
+ <li><a href="{{ pathto('index') }}">LNT Home</a> | </li>
+ <li><a href="{{ pathto('contents') }}">Documentation</a>»</li>
+{% endblock %}
Added: zorg/trunk/lnt/docs/changes.rst
URL: http://llvm.org/viewvc/llvm-project/zorg/trunk/lnt/docs/changes.rst?rev=99503&view=auto
==============================================================================
--- zorg/trunk/lnt/docs/changes.rst (added)
+++ zorg/trunk/lnt/docs/changes.rst Thu Mar 25 02:59:41 2010
@@ -0,0 +1,8 @@
+:tocdepth: 2
+
+.. _changes:
+
+Changelog
+*********
+
+.. include:: ../CHANGELOG.txt
Added: zorg/trunk/lnt/docs/conf.py
URL: http://llvm.org/viewvc/llvm-project/zorg/trunk/lnt/docs/conf.py?rev=99503&view=auto
==============================================================================
--- zorg/trunk/lnt/docs/conf.py (added)
+++ zorg/trunk/lnt/docs/conf.py Thu Mar 25 02:59:41 2010
@@ -0,0 +1,242 @@
+# -*- coding: utf-8 -*-
+#
+# LNT documentation build configuration file, created by
+# sphinx-quickstart on Fri Dec 25 10:01:58 2009.
+#
+# 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 datetime, 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.append(os.path.abspath('..'))
+
+import lnt
+
+project = "LNT"
+project_module = lnt
+
+# -- 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.doctest', 'sphinx.ext.coverage']
+
+# 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 = 'contents'
+
+# General information about the project.
+copyright = u'%s, %s' % (datetime.datetime.now().year,
+ project_module.__author__)
+
+# 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 = project_module.__version__
+# The full version, including alpha/beta/rc tags.
+release = project_module.__version__
+
+# 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 = '%Y-%m-%d'
+
+# 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 = True
+
+# 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. Major themes that come with
+# Sphinx are currently 'default' and 'sphinxdoc'.
+html_theme = 'nature'
+
+# 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 = '%Y-%m-%d'
+
+# 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 = {'index': 'indexsidebar.html'}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+html_additional_pages = {'index': 'index.html'}
+
+# If false, no module index is generated.
+#html_use_modindex = 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 = False
+
+# 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 = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = '%sdoc' % project
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+ ('contents', '%s.tex' % project, u'%s Documentation' % project,
+ project_module.__author__, '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
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_use_modindex = True
+
+
+# -- Options for Epub output ---------------------------------------------------
+
+# Bibliographic Dublin Core info.
+#epub_title = ''
+#epub_author = ''
+#epub_publisher = ''
+#epub_copyright = ''
+
+# The language of the text. It defaults to the language option
+# or en if the language is not set.
+#epub_language = ''
+
+# The scheme of the identifier. Typical schemes are ISBN or URL.
+#epub_scheme = ''
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#epub_identifier = ''
+
+# A unique identification for the text.
+#epub_uid = ''
+
+# HTML files that should be inserted before the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_pre_files = []
+
+# HTML files shat should be inserted after the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_post_files = []
+
+# A list of files that should not be packed into the epub file.
+#epub_exclude_files = []
+
+# The depth of the table of contents in toc.ncx.
+#epub_tocdepth = 3
Added: zorg/trunk/lnt/docs/contents.rst
URL: http://llvm.org/viewvc/llvm-project/zorg/trunk/lnt/docs/contents.rst?rev=99503&view=auto
==============================================================================
--- zorg/trunk/lnt/docs/contents.rst (added)
+++ zorg/trunk/lnt/docs/contents.rst Thu Mar 25 02:59:41 2010
@@ -0,0 +1,30 @@
+.. _contents:
+
+Contents
+========
+
+.. toctree::
+ :maxdepth: 2
+
+ intro
+
+ tools
+
+ changes
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+
+Module Listing
+--------------
+
+.. toctree::
+ :maxdepth: 2
+
+ modules/testing
Added: zorg/trunk/lnt/docs/intro.rst
URL: http://llvm.org/viewvc/llvm-project/zorg/trunk/lnt/docs/intro.rst?rev=99503&view=auto
==============================================================================
--- zorg/trunk/lnt/docs/intro.rst (added)
+++ zorg/trunk/lnt/docs/intro.rst Thu Mar 25 02:59:41 2010
@@ -0,0 +1,105 @@
+Introduction
+============
+
+LNT consists of two main parts, a server side web application for accessing and
+visualizing performance data, and client side utilities for easily generating
+and submitting data.
+
+LNT uses a simple and extensible format for interchanging data between the
+clients and the server; this allows the LNT server to receive and store data for
+a wide variety of applications. The web app currently contains a specialized
+viewer for LLVM nightly test data, and a generic viewer for visualizing
+arbitrary test reports.
+
+Both the LNT client and server are written in Python, however the test data
+itself can be passed in one of several formats, including property lists and
+JSON. This makes it easy to produce test results from almost any language.
+
+
+Installation
+------------
+
+These are the (current) rough steps to get a working LNT client:
+
+ 1. Install LNT:
+
+ python setup.py install
+
+ It is recommended that you install LNT into a virtualenv.
+
+If you want to run an LNT server, you will need to perform the following
+additional steps:
+
+ 2. Create a new LNT installation:
+
+ lnt create path/to/install-dir
+
+ This will create the LNT configuration file, the default database, and a
+ .wsgi wrapper to create the application. You can execute the generated app
+ directly to run with the builtin web server, or use
+
+ lnt runserver path/to/install-dir
+
+ which provides additional command line options. Neither of these servers is
+ recommended for production use.
+
+ 3. Edit the generated 'lnt.cfg' file if necessary, for example to:
+
+ a. Update the databases list.
+
+ b. Update the zorgURL.
+
+ c. Update the nt_emailer configuration.
+
+ 4. Add the 'zorg.wsgi' app to your Apache configuration. You should set also
+ configure the WSGIDaemonProcess and WSGIProcessGroup variables if not
+ already done.
+
+ If running in a virtualenv you will need to configure that as well; see the
+ `modwsgi wiki <http://code.google.com/p/modwsgi/wiki/VirtualEnvironments>`_.
+
+
+Development
+-----------
+
+Developing LNT should be done under a virtualenv (most likely in 'develop'
+mode). Currently, the tests require:
+
+ 1. 'lit', the LLVM test runner, is available.
+
+ 2. The hosted application is live at http://localhost/perf/.
+
+ 3. lnt/tests/lit.cfg should be modified to have the correct '%email_host' and
+ '%email_to' substitutions.
+
+To run the tests, use, e.g.,
+
+ lit -sv $ROOT/lnt/tests
+
+or
+
+ lit -sv $ZORG_ROOT/test
+
+to run the zorg and LNT tests all at once. You can use
+
+ python setup.py test
+
+if you prefer 'unittest' style output (this still requires that 'lit' be
+installed).
+
+Note that currently the email test will actually send you email.
+
+
+Architecture
+------------
+
+The LNT web app is currently implemented as a WSGI web app on top of Quixote,
+along with some facilities from Werkzeug. My tentative plan is to move to Jinja
+for templating, and to move to a more AJAXy web interface.
+
+The database layer uses SQLAlchemy for its ORM, and is typically backed by
+SQLite, although I have tested on MySQL on the past, and supporting other
+databases should be trivial. My plan is to always support SQLite as this allows
+the possibility of developers easily running their own LNT installation for
+viewing nightly test results, and to run with whatever DB makes the most sense
+on the server.
Added: zorg/trunk/lnt/docs/make.bat
URL: http://llvm.org/viewvc/llvm-project/zorg/trunk/lnt/docs/make.bat?rev=99503&view=auto
==============================================================================
--- zorg/trunk/lnt/docs/make.bat (added)
+++ zorg/trunk/lnt/docs/make.bat Thu Mar 25 02:59:41 2010
@@ -0,0 +1,113 @@
+ at ECHO OFF
+
+REM Command file for Sphinx documentation
+
+set SPHINXBUILD=sphinx-build
+set BUILDDIR=_build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+if NOT "%PAPER%" == "" (
+ set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+)
+
+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. 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. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+ 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
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+ goto end
+)
+
+if "%1" == "dirhtml" (
+ %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+ goto end
+)
+
+if "%1" == "pickle" (
+ %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+ echo.
+ echo.Build finished; now you can process the pickle files.
+ goto end
+)
+
+if "%1" == "json" (
+ %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+ echo.
+ echo.Build finished; now you can process the JSON files.
+ goto end
+)
+
+if "%1" == "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.
+ goto end
+)
+
+if "%1" == "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\LNT.qhcp
+ echo.To view the help file:
+ echo.^> assistant -collectionFile %BUILDDIR%\qthelp\LNT.ghc
+ goto end
+)
+
+if "%1" == "latex" (
+ %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+ echo.
+ echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+ goto end
+)
+
+if "%1" == "changes" (
+ %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+ echo.
+ echo.The overview file is in %BUILDDIR%/changes.
+ goto end
+)
+
+if "%1" == "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.
+ goto end
+)
+
+if "%1" == "doctest" (
+ %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+ echo.
+ echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+ goto end
+)
+
+:end
Added: zorg/trunk/lnt/docs/modules/testing.rst
URL: http://llvm.org/viewvc/llvm-project/zorg/trunk/lnt/docs/modules/testing.rst?rev=99503&view=auto
==============================================================================
--- zorg/trunk/lnt/docs/modules/testing.rst (added)
+++ zorg/trunk/lnt/docs/modules/testing.rst Thu Mar 25 02:59:41 2010
@@ -0,0 +1,5 @@
+:mod:`lnt.testing` -- Test Data Creation
+========================================
+
+.. automodule:: lnt.testing
+ :members:
Added: zorg/trunk/lnt/docs/tools.rst
URL: http://llvm.org/viewvc/llvm-project/zorg/trunk/lnt/docs/tools.rst?rev=99503&view=auto
==============================================================================
--- zorg/trunk/lnt/docs/tools.rst (added)
+++ zorg/trunk/lnt/docs/tools.rst Thu Mar 25 02:59:41 2010
@@ -0,0 +1,56 @@
+The ``lnt`` Tool
+================
+
+The ``lnt`` command line utility provides the following commands for client-side
+use and server-side use. The following is a list of commands and the most
+importat options, use ``lnt <toolname> --help`` for more information on any
+particular tool.
+
+Client-Side Tools
+-----------------
+
+ ``lnt checkformat [<file>]``
+ Checks the syntax of an LNT test report file. In addition to verifying that
+ LNT can read the raw format (e.g., JSON or property list), this also creates
+ a temporary in-memory database instance and insures that the test report
+ file can be imported correctly.
+
+ If run without arguments, this expects to read the input file from ``stdin``.
+
+ ``lnt convert <input path> [<output path>]``
+ Convert between LNT test report formats. By default, this will convert to
+ the property list format. You can use ``-`` for either the input (to read
+ from ``stdin) or the output (to write to ``stdout``).
+
+ ``lnt submit [--commit=1] <server url> <file>+``
+ Submits one or more files to the given server. The ``<server url>`` should
+ be the url to the actual ``submitRun`` page on the server; the database
+ being submitted to is effectively a part of this URL.
+
+ By default, this only submits the report to the server but does not actually
+ commit the data. When testing, you should verify that the server returns an
+ acceptable response before committing runs.
+
+
+Server-Side Tools
+-----------------
+
+The following tools are used to interact with an LNT server:
+
+ ``lnt create <path>``
+ Creates a new LNT server instance. This command has a number of parameters
+ to tweak the generated server, but they can all be modified after the fact
+ in the LNT configuration file.
+
+ The default server will have one database named *default*.
+
+ ``lnt import <path | config file> <file>+``
+ Import an LNT data file into a database. You can use ``--database`` to
+ select the database to write to. Note that by default this will also
+ generate report emails if enabled in the configuration, you can use
+ ``--no-email`` to disable this.
+
+ ``lnt runserver <path | config file>``
+ Start the LNT server using a development WSGI server. Additional options can
+ be used to control the server host and port, as well as useful development
+ features such as automatic reloading.
Modified: zorg/trunk/lnt/lnt/__init__.py
URL: http://llvm.org/viewvc/llvm-project/zorg/trunk/lnt/lnt/__init__.py?rev=99503&r1=99502&r2=99503&view=diff
==============================================================================
--- zorg/trunk/lnt/lnt/__init__.py (original)
+++ zorg/trunk/lnt/lnt/__init__.py Thu Mar 25 02:59:41 2010
@@ -1,6 +1,6 @@
__author__ = 'Daniel Dunbar'
__email__ = 'daniel at zuster.org'
__versioninfo__ = (0, 3, 0)
-__version__ = '.'.join(map(str, __versioninfo__))
+__version__ = '.'.join(map(str, __versioninfo__)) + 'dev'
__all__ = []
Modified: zorg/trunk/lnt/lnt/formats/__init__.py
URL: http://llvm.org/viewvc/llvm-project/zorg/trunk/lnt/lnt/formats/__init__.py?rev=99503&r1=99502&r2=99503&view=diff
==============================================================================
--- zorg/trunk/lnt/lnt/formats/__init__.py (original)
+++ zorg/trunk/lnt/lnt/formats/__init__.py Thu Mar 25 02:59:41 2010
@@ -1,5 +1,10 @@
"""
Utilities for converting to LNT's test format.
+
+LNT formats are described by dictionaries with 'name', 'read', and 'write'
+fields. Only the 'name' field is required. The 'read' field should be a callable
+taking a path_or_file object, the 'write' function should be a callable taking a
+Python object to write, and the path_or_file to write to.
"""
from AppleOpenSSLReader import format as apple_openssl
@@ -13,6 +18,11 @@
format_names = formats_by_name.keys()
def get_format(name):
+ """get_format(name) -> [format]
+
+ Loookup a format object by name.
+ """
+
return formats_by_name.get(name)
def guess_format(path_or_file):
@@ -51,6 +61,11 @@
return matches
def read_any(path_or_file, format_name):
+ """read_any(path_or_file, format_name) -> [format]
+
+ Attempt to read any compatible LNT test format file. The format_name can be
+ an actual format name, or "<auto>".
+ """
# Figure out the input format.
if format_name == '<auto>':
f = guess_format(path_or_file)
@@ -65,3 +80,5 @@
raise SystemExit("unknown input format: %r" % inFormat)
return f['read'](path_or_file)
+
+__all__ = ['get_format', 'guess_format', 'read_any'] + format_names
Modified: zorg/trunk/lnt/lnt/lnttool/__init__.py
URL: http://llvm.org/viewvc/llvm-project/zorg/trunk/lnt/lnt/lnttool/__init__.py?rev=99503&r1=99502&r2=99503&view=diff
==============================================================================
--- zorg/trunk/lnt/lnt/lnttool/__init__.py (original)
+++ zorg/trunk/lnt/lnt/lnttool/__init__.py Thu Mar 25 02:59:41 2010
@@ -80,7 +80,7 @@
"""submit a test report to the server."""
from optparse import OptionParser, OptionGroup
- parser = OptionParser("%%prog %s [options] url files+" % name)
+ parser = OptionParser("%%prog %s [options] <url> <file>+" % name)
parser.add_option("", "--commit", dest="commit", type=int,
default=False)
Modified: zorg/trunk/lnt/lnt/lnttool/create.py
URL: http://llvm.org/viewvc/llvm-project/zorg/trunk/lnt/lnt/lnttool/create.py?rev=99503&r1=99502&r2=99503&view=diff
==============================================================================
--- zorg/trunk/lnt/lnt/lnttool/create.py (original)
+++ zorg/trunk/lnt/lnt/lnttool/create.py Thu Mar 25 02:59:41 2010
@@ -75,7 +75,7 @@
"""create an LLVM nightly test installation"""
from optparse import OptionParser, OptionGroup
- parser = OptionParser("%%prog %s [options] [<path|config file>]" % name)
+ parser = OptionParser("%%prog %s [options] <path>" % name)
parser.add_option("", "--name", dest="name", default="LNT",
help="name to use for the installation [%default]")
parser.add_option("", "--config", dest="config", default="lnt.cfg",
Modified: zorg/trunk/lnt/lnt/lnttool/import_data.py
URL: http://llvm.org/viewvc/llvm-project/zorg/trunk/lnt/lnt/lnttool/import_data.py?rev=99503&r1=99502&r2=99503&view=diff
==============================================================================
--- zorg/trunk/lnt/lnt/lnttool/import_data.py (original)
+++ zorg/trunk/lnt/lnt/lnttool/import_data.py Thu Mar 25 02:59:41 2010
@@ -9,7 +9,7 @@
from optparse import OptionParser, OptionGroup
- parser = OptionParser("%%prog %s [options] <path|config-file> file+" %name)
+ parser = OptionParser("%%prog %s [options] <path|config-file> <file>+"%name)
parser.add_option("", "--database", dest="database", default="default",
help="database to write to [%default]")
parser.add_option("", "--format", dest="format",
Modified: zorg/trunk/lnt/lnt/testing/__init__.py
URL: http://llvm.org/viewvc/llvm-project/zorg/trunk/lnt/lnt/testing/__init__.py?rev=99503&r1=99502&r2=99503&view=diff
==============================================================================
--- zorg/trunk/lnt/lnt/testing/__init__.py (original)
+++ zorg/trunk/lnt/lnt/testing/__init__.py Thu Mar 25 02:59:41 2010
@@ -1,5 +1,9 @@
"""
Utilities for working with the LNT test format.
+
+Clients can easily generate LNT test format data by creating Report objects for
+the runs they wish to submit, and using Report.render to convert them to JSON
+data suitable for submitting to the server.
"""
import time
@@ -13,7 +17,37 @@
t = time.strptime(start_time, '%Y-%m-%d %H:%M:%S')
return t.strftime('%Y-%m-%d %H:%M:%S')
+class Report:
+ """Information on a single testing run.
+
+ In the LNT test model, every test run should define exactly one machine and
+ run, and any number of test samples.
+ """
+ def __init__(self, machine, run, tests):
+ self.machine = machine
+ self.run = run
+ self.tests = list(tests)
+
+ assert isinstance(self.machine, Machine)
+ assert isinstance(self.run, Run)
+ for t in self.tests:
+ assert isinstance(t, TestSamples)
+
+ def render(self):
+ return json.dumps({ 'Machine' : self.machine.render(),
+ 'Run' : self.run.render(),
+ 'Tests' : [t.render() for t in self.tests] },
+ sort_keys=True, indent=4)
+
class Machine:
+ """Information on the machine the test was run on.
+
+ The info dictionary can be used to describe additional information about the
+ machine, for example the hardware resources or the operating environment.
+
+ Machines entries in the database are uniqued by their name and the entire
+ contents of the info dictionary.
+ """
def __init__(self, name, info={}):
self.name = str(name)
self.info = dict((str(key),str(value))
@@ -24,6 +58,19 @@
'Info' : self.info }
class Run:
+ """Information on the particular test run.
+
+ The start and end time should always be supplied with the run. Currently,
+ the server uses these to order runs. In the future we will support
+ additional ways to order runs (for example, by a source revision).
+
+ As with Machine, the info dictionary can be used to describe additional
+ information on the run. This dictionary should be used to describe
+ information on the software-under-test that is constant across the test run,
+ for example the revision number being tested. It can also be used to
+ describe information about the current state which could be useful in
+ analysis, for example the current machine load.
+ """
def __init__(self, start_time, end_time, info={}):
if start_time is None:
start_time = datetime.datetime.now()
@@ -41,6 +88,33 @@
'Info' : self.info }
class TestSamples:
+ """Test sample data.
+
+ The test sample data defines both the tests that were run and their
+ values. The server automatically creates test database objects whenever a
+ new test name is seen.
+
+ Test names are intended to be a persistent, recognizable identifier for what
+ is being executed. Currently, most formats use some form of dotted notation
+ for the test name, and this may become enshrined in the format in the
+ future. In general, the test names should be independent of the
+ software-under-test and refer to some known quantity, for example the
+ software under test. For example, 'CINT2006.403_gcc' is a meaningful test
+ name.
+
+ The test info dictionary is intended to hold information on the particular
+ permutation of the test that was run. This might include variables specific
+ to the software-under-test . This could include, for example, the compile
+ flags the test was built with, or the runtime parameters that were used. As
+ a general rule, if two test samples are meaningfully and directly
+ comparable, then the should have the same test name but different info
+ paramaters.
+
+ The report may include an arbitrary number of samples for each test for
+ situations where the same test is run multiple times to gather statistical
+ data.
+ """
+
def __init__(self, name, data, info={}):
self.name = str(name)
self.info = dict((str(key),str(value))
@@ -52,21 +126,4 @@
'Info' : self.info,
'Data' : self.data }
-class Report:
- def __init__(self, machine, run, tests):
- self.machine = machine
- self.run = run
- self.tests = list(tests)
-
- assert isinstance(self.machine, Machine)
- assert isinstance(self.run, Run)
- for t in self.tests:
- assert isinstance(t, TestSamples)
-
- def render(self):
- return json.dumps({ 'Machine' : self.machine.render(),
- 'Run' : self.run.render(),
- 'Tests' : [t.render() for t in self.tests] },
- sort_keys=True, indent=4)
-
-__all__ = ['Machine', 'Run', 'TestSamples', 'Report']
+__all__ = ['Report', 'Machine', 'Run', 'TestSamples']
Modified: zorg/trunk/lnt/lnt/util/ImportData.py
URL: http://llvm.org/viewvc/llvm-project/zorg/trunk/lnt/lnt/util/ImportData.py?rev=99503&r1=99502&r2=99503&view=diff
==============================================================================
--- zorg/trunk/lnt/lnt/util/ImportData.py (original)
+++ zorg/trunk/lnt/lnt/util/ImportData.py Thu Mar 25 02:59:41 2010
@@ -7,10 +7,14 @@
def import_and_report(config, db_name, db, file, log, format, commit=False,
show_sample_count=False, disable_email=False):
"""
- import_file(config, db_name, db, file) -> (success, run, log)
-
- Import a test data file into the database. On success, run is the newly
- imported run.
+ import_and_report(config, db_name, db, file, log, format,
+ [commit], [show_sample_count],
+ [disable_email]) -> (success, run)
+
+ Import a test data file into an LNT server and generate a test report. On
+ success, run is the newly imported run. Note that success is uneffected by
+ the value of commit, this merely changes whether the run (on success) is
+ committed to the database.
"""
numMachines = db.getNumMachines()
numRuns = db.getNumRuns()
More information about the llvm-commits
mailing list