Note
This part of the documentation is extremely sparse and will be updated very soon.
One of the main goals of virtstrap is to provide a simple way to create plugins that can extend the functions of virtstrap for each project. Plugins can add functionality using two different objects:
This quickstart guide goes through the creation of a hook. Eventually this will contain information on creating new commands.
In order to understand plugins, you have to understand a bit about how virtstrap works. Virtstrap has multiple packages explained below:
So let’s start by creating a new virtstrap-local plugin.
Like mentioned previously, virtstrap-local is the suggested package to extend with plugins. The reason is that your changes won’t interfere with other projects on your system and it allows your plugins to be used in a repeatable fashion.
Virtstrap plugins, like buildout recipe’s, are simply python packages. The package simple registers a module to an entry point and virtstrap takes over from there. So let’s start out by creating a new package for to create our new plugin:
$ mkdir virtstrap-new-plugin
$ cd virtstrap-new-plugin
$ mkdir virtstrap_new_plugin
$ touch virtstrap_new_plugin/__init__.py
Note
For the time being, virtstrap assumes you’re using a unix environment. At this time windows is untested although plans are in the works for a future release.
What we just did is create the scaffolding for a new python package. Next, we need to create a setup.py file. Open up your favorite editor (mine is vim) and copy this code (you can edit this if you are actually going to use this):
from setuptools import setup, find_packages
import sys, os
version = '0.0.0-dev'
setup(
name='virtstrap-new-plugin',
version=version,
description="A new virtstrap plugin",
long_description="""A new virtstrap plugin""",
classifiers=[],
keywords='virtstrap',
author='John Doe',
author_email='someone@someemail-place.com',
url='',
license='MIT',
packages=find_packages(exclude=['ez_setup', 'examples', 'tests']),
include_package_data=True,
zip_safe=False,
install_requires=[
#'virtstrap-local',
],
entry_points={
'virtstrap_local.plugins': [
'plugin = virtstrap_new_plugin.plugin',
]
},
)
In general the best way to get something new out of virtstrap is to use hooks to listen for events that commands issue. Commands will almost always issue the before and after event. The easiest way to determine what events are available is to use the event attribute of a command.
Here is a simple example:
from virtstrap import hooks
@hooks.create('install', ['after'])
def new_install_hook(event, options, **kwargs):
print "I appear after install has completed!"
So what did this all do? Let’s break it down!
The above example is the bare minimum you’d need to write to create a hook. Really, it’s pretty lame. It simply prints the statement I appear after install has completed upon receiving the after event from the install command. However, let’s do something a tad more interesting:
from virtstrap import hooks
from virtstrap.log import logger
@hooks.create('install', ['after'])
def new_install_hook(event, options, project=None, **kwargs):
logger.info('The current path of the project is %s' % project.path())
There are three changes here.
There, that’s a bit more interesting. However, it still does almost nothing. Let’s do something crazy - like initialize a git repository!
Here goes:
from virtstrap import hooks
from virtstrap.log import logger
from virtstrap.utils import call_subprocess
@hooks.create('install', ['after'])
def new_install_hook(event, options, project=None, **kwargs):
logger.info('Initializing a git repository for project at %s'
% project.path())
call_subprocess(['git', 'init', project.path()], show_stdout=False)
WOO! Finally, we’re getting somewhere. This is what just happened:
In order for you to use this plugin let’s test it out with a new project.
Do the following in any directory you wish to use:
$ mkdir test-project
$ cd test-project
Next create a VEfile:
$ vim VEfile
Place this inside of it
plugins:
- virtstrap-new-plugin:
- file://PATH_TO_PLUGIN
Just replace PATH_TO_PLUGIN with the actual path to the plugin’s directory.
Finally, from within your new project directory do this:
$ vstrap init
You should see the following:
... (normal virtstrap messages)
Initializing a git repository for project at SOME_DIRECTORY
... (more messages)
Now you can do this:
$ git status
And it you should see that there’s a git repository in your current directory!
As stated previously, this example isn’t very useful in a real project. If you’d like to see a useful example of this type of plugin checkout virtstrap-ruby-bundler