x/anvil
Code Issues Proposed changes

Some small doc cleanups.

Browse Source 
Change-Id: Ib1071febe1c08c129b44910bb63b49f28f292b9b
This commit is contained in:
Joshua Harlow 2013-06-05 20:35:14 -07:00
parent 8360035d2d
commit 27f9e46fcf
6 changed files with 68 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/source/index.rst
View File

@ -4,7 +4,7 @@
ANVIL Documentation
=====================
.. rubric:: Everything about ANVIL, a set of **python** scripts and utilities to forge raw openstack into a productive tool!
.. rubric:: Everything about ANVIL, a set of **python** scripts and utilities to forge raw openstack into a productive tool!
----

11
docs/source/topics/bugshugscode.rst
View File

@ -26,7 +26,12 @@ The source code is on github located at:
https://github.com/stackforge/anvil/
Feel free to fork it and contribute to it. You can also get a tarball or zip archive of the code.
Feel free to fork it and contribute to it.
Bugs
----
https://bugs.launchpad.net/anvil
Branches
--------
@ -39,9 +44,9 @@ https://github.com/stackforge/anvil/branches
Hacking
=======
Feel free to hack but please try to follow the `hacking guidelines`_
Feel free to hack but please try to follow the `hacking guidelines`_.
.. _apache version 2.0 license: https://github.com/stackforge/anvil/blob/master/LICENSE
.. _launchpad’s issue tracking system: http://launchpad.net/anvil
.. _hacking guidelines: https://github.com/stackforge/anvil/blob/master/README.md
.. _hacking guidelines: https://github.com/stackforge/anvil/blob/master/HACKING.md

13
docs/source/topics/dev_notes/addingowndistro.rst
View File

@ -70,16 +70,3 @@ we can add in your own distribution support.
After adding make sure you reference them in your **conf/distros** yaml file so that the correct subclass will be used. If you are going
to want to create package files from the installed code then you will need to hook-in to a file similar
to the rpm module that exists there.
Bring back the dead!
----------
If you are adding in debian/ubuntu/fedora support please check out the older code that existed that did this
which was removed due to it being unmatained. It might help ease the process if these files are just brought
back from the dead and fixed as needed...
+ https://github.com/yahoo/Openstack-Anvil/blob/2012.5.11/anvil/packaging/apt.py
+ https://github.com/yahoo/Openstack-Anvil/blob/2012.5.11/anvil/distros/oneiric.py
+ https://github.com/yahoo/Openstack-Anvil/blob/2012.5.11/conf/distros/ubuntu-oneiric.yaml
+ https://github.com/yahoo/Openstack-Anvil/blob/2012.5.11/conf/distros/fedora-16.yaml

56
docs/source/topics/dev_notes/architecture.rst
View File

@ -1,8 +1,8 @@
.. _architecture:
====
How anvil is architected.
====
========================
How anvil is architected
========================
This little ``HOWTO`` can be used by those who wish to
understand how anvil does things and why some of its
@ -11,48 +11,52 @@ architectural decisions were made.
Diving in!
----------
^^^^^^^^^^
^^^^^^^^^^^^^^^^
A little history
^^^^^^^^^^
^^^^^^^^^^^^^^^^
Once upon a time there was a idea of replacing the then existing `devstack <http://devstack.org/>`_
with a more robust, more error-tolerant and more user/developer friendly OpenStack
setup toolkit. Since the existing `devstack <http://devstack.org/>`_ did (and still
does not support very well) complex intercomponent (and interpackage management system) dependencies,
and installing/starting/stopping/uninstalling of OpenStack components it was thought
that there could be a toolkit that could handle this better. It would also be in
Python the language of choice for the rest of the OpenStack components thus making
it easier to understand for programmers who are already working in OpenStack code.
Never fear though, it was meant to be used by those who actually wanted to understand
the setup of OpenStack by looking at similar code but this was targeted as not being
a necessity. Thus *devstack2* was born which was later renamed *devstack.py* and after a
little while once again got renamed to *anvil*.
does not support very well) complex intercomponent (and interpackage management system) dependencies
and installing/packaging/starting/stopping/uninstalling of OpenStack components.
^^^^^^^^^^
To solve this problem it was thought that there could be a toolkit that could handle this better.
It would also be in Python the language of choice for the rest of the OpenStack components thus making
it easier to understand for programmers who are already working in OpenStack code. Thus *devstack2* was
born which was later renamed *devstack.py* and after a little while once again got renamed to *anvil*.
^^^^^^^^^
Structure
^^^^^^^^^^
^^^^^^^^^
Anvil is designed to have the following set of software components:
* **Actions:** an action is a sequence of function calls on a set of implementing
classes which follows a logically flow from one step to the next. At the end of
each step an action may choose to negate a step of another action.
*The currently implemented actions and stages are the following*:
* Preparing
* Downloading source code
* Post-download patching of the source code
* Deep dependency & requirement analysis
* Downloading and packaging of missing python dependencies
* Packaging downloaded source code
* Creation of a repository with all built packages & dependencies
* Install
* Downloading
* Post-download patching
* Configuring
* Pre-installing
* Installing
* Installing packages from previously prepared repository
* Post-installing
* Uninstall
* Unconfiguring
* Pre-uninstalling
* Uninstalling
* Uninstalling previously installed packages
* Post-uninstalling
* Starting
@ -71,14 +75,16 @@ Anvil is designed to have the following set of software components:
into a file so that if ``ctrl-c`` aborts anvil and later the install is restarted
anvil can notice that the previous phases have already been completed and those
phases can be skipped. This is how anvil does action and step resuming.
* **Components:** a component is a class which implements the above steps (which
are literally methods on an instance) and is registered with the persona and
configuration to be activated. To aid in making it easier to add in new components
a set of *generic* base classes exist that provide common functionality that
should work in most simplistic installs. These can be found in
``anvil/components/__init__.py``. All current components that exist either use
``anvil/components/``. All current components that exist either use
these base classes directly or inherit from them and override functions to
provide additional capabilities needed to perform the specified action.
* **Distributions:** a distribution is a yaml file that is tied to a operating
system distribution and provides references for components to use in a generic
manner. Some of these references include how to map a components ``pip-requires``
@ -86,12 +92,13 @@ Anvil is designed to have the following set of software components:
or ``apt``) or what non-specified dependencies are useful in getting the component
up and running (such as ``guestfish`` for image mounting and manipulation).
Other helpful references include allowing for components to specify standard
identifiers for configuration such as ``pip`` but the underlying yaml file can
identifiers for configuration such as ``pip``. This allows the underlying yaml file to
map the ``pip`` command to a distribution-centric command (in RHEL it its really
named ``pip-python``), see the *commands* key in the yaml files for examples
of these settings. Note that each distribution yaml file that exists in ``conf/distros``
provides this set of references for each component and gets selected based on the
yaml key in that file named *platform_pattern*.
* **Configuration:** central to how anvil operates is the ability to be largely
configuration driven (code when you need it but avoid it if you can).
Distributions as seen by the ``conf/distros`` folder specify
@ -103,7 +110,8 @@ Anvil is designed to have the following set of software components:
configuration drive approach (as much as can be possible) was a key design goal that
drives how anvil was and is developed. It has even seemed to be ahead of its time due
to how anvil has a distribution yaml file that has specified component dependencies
long before the OpenStack community even recgonized such a dependency list was useful.
long before the OpenStack community even recognized such a dependency list was useful.
* **Personas:** a persona is a way for anvil to know what components (and possibly
subsystems of those components) you wish to have the given action applied to. Since
not everyone can agree on what is an install of OpenStack this concept allows for

38
docs/source/topics/features.rst
View File

@ -11,26 +11,26 @@ Features
* **Installing**:
* Automatically downloading source from git and performing tag/branch checkouts.
* Automatically verifying and translating ``test-requires`` and ``pip-requires`` files to known `pypi`_/rpm packages.
* Automatically installing and building dependencies/packaging (`pypi`_ and rpm) specifics for you.
* Automatically configuring the needed files, symlinks, adjustments, tweaks.
* Automatically verifying and translating requirement files to known `pypi`_/rpm packages.
* Automatically installing and building missing dependencies (`pypi`_ and rpm) for you.
* Automatically configuring the needed files, symlinks, adjustments, and any patches.
* **Starting**: starting of the components sub-programs with
the needed configuration via the common `daemon`_ model
the needed configuration via the common `daemon`_ model.
* Also creates a ``pid``, ``stderr`` and ``stdout`` file set for debugging/examination.
* **Stopping**: stopping of the previously started components
* **Uninstalling**: getting you back to an initial 'clean' state
* **Stopping**: stopping of the previously started components.
* **Uninstalling**: getting you back to an initial 'clean' state.
* Removing installed configuration.
* Undoing of installed files/directories.
* Removing of packages installed.
* **Testing**: running each components unit tests (and in the future performing a simple set of integration tests)
* **Packaging**: creating a basic set of packages that matches the components selected
* **Testing**: automatically running each components unit tests.
* **Packaging**: creating a basic set of packages that matches the components selected.
- Supports automatic injection of dependencies, creation of change log from git history.
- Supports automatic injection of dependencies and creation of a ``changelog`` from git history.
* **Status**: checking the status of the running components sub-programs
@ -38,25 +38,25 @@ Features
- Written in **python** so it matches the style of other `OpenStack`_ components.
- **Code decoupling** (thus encouraging re-use by others)
* Components/actions are isolated as individual classes...
* Components & actions are isolated as individual classes.
* Supports installation *personas* that define what is to be installed, thus
decoupling the 'what' from the 'how'.
- **Install/start/stop... resumption** so that when you install you can ``ctrl+c`` and resume later (where applicable).
- Extensive **logging** (and debug mode)
* All commands ran are logged, all configuration files read/write...
* All commands executed are logged, all configuration files read/written (and so on).
- **Package tracking and building**
* Anvil can create a single rpm of your installation, as well as build or include all needed dependencies so that
the software that is installed can be installed repeatedly and reliably in the future.
* This allows for installations to use the distributions native packages (when applicable)
as well as provides a list of pips which should be packaged by that distribution before the given `OpenStack`_ release
is stabilized.
* This also allows for releases of anvil to track exactly how (and what packages and what mapping) is needed for a given
release tag (which maps to a given `OpenStack`_ release tag), thus freezing what is needed for that release to a
known set.
* Creation of a single rpm of your installation.
* This freezes what is needed
for that release to a known set of packages and dependencies.
* Automatically building and/or including all needed dependencies.
* Includes application of your distributions native packages (when applicable).
.. _epel: http://fedoraproject.org/wiki/EPEL
.. _forking: http://users.telenet.be/bartl/classicperl/fork/all.html

13
docs/source/topics/solvedproblems.rst
View File

@ -4,12 +4,15 @@
Solved Problems
===============
Solutions
=========
Mysql user denied
MySQL user denied
-----------------
This seems common and can be fixed by running one of the steps at
http://dev.mysql.com/doc/refman/5.0/en/resetting-permissions.html
The temporary folder for building (/tmp/XYZ) is not owned by your user!
-----------------------------------------------------------------------
This is a new feature of pip>=1.3 where it seems to incorrectly handle the SUDO
user. To get around this just remove the above directory and reactivate the
appropriate ANVIL command.