Introduction
The PVSS Bootstrapper (simply called "Bootstrapper" afterwards) is an outside-PVSS tool/API to manage projects. It can be used either as a cross-platform command line tool or as a Python module.
The Bootstrapper can be useful in the following cases:
-
Testing.
-
Frequent recreation of test projects.
-
Start/stop a pre-created test project from a script.
-
-
Development.
-
Test installation of your components without click burden.
-
Create, deploy and trash your multi-project setup as much as you want.
-
-
Multi-users development and testing.
-
Send your colleagues your daily developments in a single deployment script.
-
-
Or whatever please you, it’s flexible.
It offers automation, scripting and command line facilities for the following actions:
-
Starting and stopping a specific project.
-
Stopping all running projects.
-
Registering and unregistering an existing project.
-
Creating, overwriting or deleting a project.
-
Deploying the fwInstallation tool.
-
Installing components, even from Zip files or SVN repositories.
Quick start
In this section you will dive quickly into the subject. You will setup the installation of the Bootstrapper and try a few examples. You will see how to create and start a project from the command-line tool and from a Python script.
Installation
-
Windows of Linux.
-
PVSS 3.8 (not yet tested on 3.9/3.10).
-
Usually: Python (see note).
-
NOT Python 3.
-
Python 2.7 for a full experience.
-
Otherwise Python >= 2.3 with the argparse module installed in addition.
-
Pysvn in case you wish to use the SVN capabilities for installing components.
-
|
No Python It is still possible to use the Bootstrapper without Python. Other OS-specific call scripts are available (Shell and Batch).
However they are severely restricted in usability. Refer to the simple scripts section for more information. |
You can find stable versions of the Bootstrapper on this web page: http://cern.ch/enice/PVSS+Bootstrapper
If you are interested in using the latest development version, the Bootstrapper is available on SVN: https://svn.cern.ch/reps/en-ice-svn/trunk/tools/JCOP/Projects/Framework/Utilities/PVSSBootstrapper
The Bootstrapper is made of two parts:
-
A script, be it Python, Shell or Batch, parsing and checking arguments and then calling the second part.
-
A pseudo PVSS project with a collection of CONTROL scripts doing the main work.
Therefore, the Bootstrapper is not just one executable. It needs to reside in its own "installation directory". However, there are no constraints on where this folder should be. You just need to have execution rights on one of the calling scripts.
Extract, checkout or export the Bootstrapper in this installation directory from the source you have chosen.
If you choose the Python flavour of the Bootstrapper, the installation script will take care of these details. For these, go into the folder of the Bootstrapper you just downloade and enter on a prompt:
sudo python setup.py install
This will install the Bootstrapper in the site-packages directory of your Python installation and add it to your system path and Python import path.
|
If you run the installation on a machine with an old version of Python (like 2.4) the installation script will attempt to download the argparse module from the internet. If you do not have internet access from your machine (Technical Network for instance), install the argparse module manually beforehand. |
Execution
To use the Bootstrapper as a command line program, you need to either call it from its installation directory or add it to the PATH environment variable of your system if not already done in the installation procedure.
Here is how you can call the command-line python script of the Bootstrapper.
PVSSBootstrapper Args...
Help
A detailed help is available directly through the command line tool argument -h/--help.
To get general information on the tool and the supported functions:
PVSSBootstrapper --help
To get detailed information on a specific function, such as startProject for instance:
# Supposes the Bootstrapper is available in the PATH
PVSSBootstrapper startProject --help
Be sure to put the -h/--help flag AFTER the function name. Otherwise you will just get the general help.
Creating a project
The function createProject allows you to generate from scratch a PVSS project. It has two arguments: the directory where the project will be created, and the project name.
PVSSBootstrapper createProject Path/To/Sandbox MyTestProj
This will result in having the project MyTestProj being created inside the Sandbox directory:
-
…
-
Sandbox
-
MyTestProj
-
config
-
panels
-
scripts
-
…
-
-
-
Path/To/Sandbox can be an absolute or a relative path.
If you want to recreate the same project you can use the overwrite option:
PVSSBootstrapper createProject Path/To/Sandbox MyTestProj --overwrite
Various options are available to:
-
Overwrite an existing project.
-
Specify a system name or number.
-
Specify ports for pmon, data, event and dist managers.
Check-out the reference for the createProject function or the command help.
Starting a project
The function startProject allows you to start a PVSS project. It has one argument: the project name or path.
# With the project name
PVSSBootstrapper startProject MyTestProj
# With the project path
PVSSBootstrapper startProject Path/To/Sandbox/MyTestProj
In case the project was not registered on this machine before, it will automatically register it.
Various options are available to:
-
Force a restart of an already running project.
-
Control the opening of the console and the log viewer.
-
Not automatically register the project.
-
Provide a PVSS user and password to run the project.
Check-out the reference for the startProject function or the command help.
Using the Python interface
Each function of the Bootstrapper is available as a Python function you can access by importing the PVSSBootstrapper module. This makes the Bootstrapper easily accessible from a Python script or a Python interactive interpreter.
Options for these functions are named arguments, and are the same as the ones of the command line tool, except they are written in camelCase (the lower camel case version).
In case of error, a PVSSBootstrapperException is raised.
from PVSSBootstrapper import PVSSBootstrapper
try:
PVSSBootstrapper.createProject('Path/To/Sandbox', 'MyTestProj', overwrite=True)
except PVSSBootstrapper.PVSSBootstrapperException as ex:
print ex
from PVSSBootstrapper import PVSSBootstrapper
try:
PVSSBootstrapper.startProject('MyTestProj')
except PVSSBootstrapper.PVSSBootstrapperException as ex:
print ex
You can also make it shorter:
from PVSSBootstrapper import PVSSBootstrapper as PBS
PBS.startProject('MyTestProj')
Reading arguments from a file
If you find yourself always calling the Bootstrapper with the same arguments you can write them in a file and have the script read them.
First, write in a text files all your arguments, one per line (as if replacing spaces by new lines):
createProject --overwrite Path/To/Sandbox MyTestProject
Then, call the Bootstrapper by preceding the file name with a @:
PVSSBootstrapper @createMyTestProject.txt
You can also add other arguments on the command line directly. The order (and so priority) will be according to their declaration order (last mention of an argument has priority on previous mentions). This is mainly for optional arguments taking a value. So you can overwrite the value of an option declared in a file for instance.
Function references
PVSSBootstrapper [-h] [--pvss VERSION] [-g]
{startProject,stopProject,stopAllProjects,registerProject,
unregisterProject,deleteProject,createProject,deployZip,
setComponentInstallationFolder,installComponent}
...
PVSSBootstrapper.startProject(...)
PVSSBootstrapper.stopProject(...)
PVSSBootstrapper.stopAllProjects(...)
PVSSBootstrapper.isProjectRunning(...)
PVSSBootstrapper.registerProject(...)
PVSSBootstrapper.unregisterProject(...)
PVSSBootstrapper.deleteProject(...)
PVSSBootstrapper.isProjectRegistered(...)
PVSSBootstrapper.createProject(...)
PVSSBootstrapper.getProjectPath(...)
PVSSBootstrapper.deployZip(...)
PVSSBootstrapper.setComponentInstallationFolder(...)
PVSSBootstrapper.installComponent(...)
Optional arguments are documented in this section: General purpose options.
Function | Description | Documentation |
---|---|---|
createProject |
Create a PVSS project. |
|
getProjectPath |
Resolve the project path with a PVSS project name. |
|
listProjects |
List all PVSS projects. |
|
startProject |
Start a PVSS project. |
|
stopProject |
Stop a PVSS project. |
|
stopAllProjects |
Stop all PVSS projects. |
|
isProjectRunning |
Is a PVSS project running? |
|
deployZip |
Extract a Zip file inside a project. |
|
setComponentInstallationFolder |
Set the folder in which the installation tool will install the components. |
|
installComponent |
Install one or many components. |
|
registerProject |
Register a PVSS project. |
|
unregisterProject |
Unregister a PVSS project. |
|
deleteProject |
Delete a PVSS project (delete the files!). |
|
isProjectRegistered |
Is a PVSS project registered? |
Through all this reference documentation the command line arguments and the Python arguments are described. When listing optional arguments in detail, the ones refering to a Python argument name will be highlighted in this way.
Create project
Create a PVSS project.
PVSSBootstrapper createProject INSTALL_PATH PROJECT_NAME
[-h] [--system-number N]
[--system-name NAME] [--overwrite]
[--pmon-port N] [--data-port N]
[--event-port N] [--dist-port N]
PVSSBootstrapper.createProject(INSTALL_PATH, PROJECT_NAME,
overwrite=True,
systemNumber=N, systemName=NAME,
pmonPort=N, dataPort=N,
eventPort=N, distPort=N)
-
INSTALL_PATH
-
Directory where the project will be created.
-
-
PROJECT_NAME
-
The name of the project to create.
-
-
-h, --help
-
Show a specific help message and exit.
-
-
--system-number N or systemNumber=N
-
Set the system number of the project to create (default: 1).
-
-
--system-name NAME or systemName=NAME
-
Set the system name of the project to create (default: "dist_" + systemNumber).
-
-
--overwrite or overwrite=True
-
If a similar project exists it will be deleted first (default: False).
-
-
--pmon-port N or pmonPort=N
-
Set the port for pmon of the project to create (default: 0).
-
-
--data-port N or dataPort=N
-
Set the port for data manager of the project to create (default: 0).
-
-
--event-port N or eventPort=N
-
Set the port for event manager of the project to create (default: 0).
-
-
--dist-port N or distPort=N
-
Set the port for distributed manager of the project to create (default: 0).
-
Get project path
Resolve the project path with a PVSS project name.
In python, returns a string.
With command-line, it writes on the output the project path.
PVSSBootstrapper getProjectPath PROJECT_NAME [-h]
PVSSBootstrapper.getProjectPath(PROJECT_NAME)
-
PROJECT_NAME
-
Name of the project to stop.
-
-
-h, --help
-
Show a specific help message and exit.
-
List projects
List all PVSS project names registered on the machine.
In python, returns a list of strings.
With command-line, it writes on the output each project name, one per line.
PVSSBootstrapper listProject [-h]
PVSSBootstrapper.listProject()
-
-h, --help
-
Show a specific help message and exit.
-
Start project
Start a PVSS project.
If a path to the project is given instead of just a name and if this project is not registered, it will be automatically registered unless you use the dontRegister option.
If the project is already running it will not restart it unless you use the restart option.
The Bootstrapper will wait until all the managers in always mode are running.
This function opens automatically the console and the log viewer unless you use the noConsole and noLogViewer options.
PVSSBootstrapper startProject PROJECT
[-h] [--restart]
[--user USER] [--password PASSWORD]
[--no-console] [--no-log-viewer]
[--dont-register] [--dont-wait]
PVSSBootstrapper.startProject(PROJECT,
restart=True,
user=USER, password=PASSWORD,
noConsole=True, noLogViewer=True,
dontRegister=True, dontWait=True)
-
PROJECT
-
Path or name of the project to start.
-
-
-h, --help
-
Show a specific help message and exit.
-
-
--restart or restart=True
-
If the project is already running, stop it then start it again (default: False).
-
-
--user USER or user=USER
-
PVSS user (default: "").
-
-
--password PASSWORD or password=PASSWORD
-
PVSS password (default: "").
-
-
--no-console or noConsole=True
-
Do not open a console (default: False).
-
-
--no-log-viewer or noLogViewer=True
-
Open a log viewer (default: False).
-
-
--dont-register or dontRegister=True
-
Do not automatically register the project if it is not registered already and a project path is provided (default: False).
-
-
--dont-wait or dontWait=True
-
Do not wait for the start of the project and return immediately after the start command (default: False).
-
Stop project
Stop a PVSS project.
PVSSBootstrapper stopProject PROJECT_NAME [-h]
PVSSBootstrapper.stopProject(PROJECT_NAME)
-
PROJECT_NAME
-
Name of the project to stop.
-
-
-h, --help
-
Show a specific help message and exit.
-
Stop all projects
Stop all PVSS projects currently running on the machine.
PVSSBootstrapper stopAllProjects [-h]
PVSSBootstrapper.stopAllProjects()
-
-h, --help
-
Show a specific help message and exit.
-
Is project running?
Tell if a PVSS project is running or not.
In python, returns a boolean.
With the command line, first it writes on the output True or False. Then it sets the exit code to 0 for false and 1 for true. In bash, for instance, you can retrieve it with $?.
PVSSBootstrapper isProjectRunning PROJECT_NAME [-h]
PVSSBootstrapper.isProjectRunning(PROJECT_NAME)
-
PROJECT_NAME
-
Name of the project.
-
-
-h, --help
-
Show a specific help message and exit.
-
Deploy Zip file
Extract a Zip file inside a project. The content of the Zip file will be extracted at the root of the project.
This function can be used to deploy the fwInstallationTool prior installing components for instance.
PVSSBootstrapper deployZip PROJECT_NAME ZIP_FILE [-h]
PVSSBootstrapper.deployZip(PROJECT_NAME, ZIP_FILE)
-
PROJECT_NAME
-
Name of the project where the Zip file will be extracted.
-
-
ZIP_FILE
-
Zip file to extract.
-
-
-h, --help
-
Show a specific help message and exit.
-
Component installation folder
Set the folder in which the installation tool will install the components. The project need to be running and it will use the fwInstallation tool locally available in the project. See Deploy Zip reference.
A relative path will be relative to the project installation directory. Avoid paths starting with ../.
PVSSBootstrapper setComponentInstallationFolder PROJECT_NAME FOLDER [-h]
PVSSBootstrapper.setComponentInstallationFolder(PROJECT_NAME, FOLDER)
-
PROJECT_NAME
-
Name of the project where the Zip file will be extracted.
-
-
FOLDER
-
Folder where the components will be installed.
-
-
-h, --help
-
Show a specific help message and exit.
-
Install component
Install one or many components. The project need to be running and it will use the fwInstallation tool locally available in the project. See Deploy Zip reference.
If you never installed a component in the given project before you should set the component installation folder first. See Set component installation folder reference.
A component source can be either a simple directory containing components, a Zip file or a SVN repository. If the source is a Zip file, the Bootstrapper will automatically detect the first folder containing XML files as being the root of the component source inside the Zip file.
Zip files will be extracted in a temporary directory before passing it to the installation tool. SVN repositories will be exported similarly. The temporary directories created will be automatically deleted before the Bootstrapper returns.
The Bootstrapper will use your local SVN profile to authenticate on the given servers. In case you never authenticated on a server before it will prompt you for username and password. If a local password storage is available it will then register them automatically.
Python-svn (pysvn) need to be installed for SVN sources.
PVSSBootstrapper installComponent PROJECT_NAME
[-h]
[--sources SOURCE [SOURCE ...]]
[--components COMPONENT [COMPONENT ...]]
PVSSBootstrapper.installComponent(PROJECT_NAME, [SOURCE, ...], [COMPONENT, ...])
-
PROJECT_NAME
-
Name of the target project.
-
-
[SOURCE, …]
-
Local directory, Zip file or SVN repository where components can be found. You have to provide at least one source. In Python it can be a single string or a list of string.
-
-
[COMPONENT, …]
-
Component names in the form component.xml. You have to provide at least one component name. In Python it can be a single string or a list of string.
-
-
-h, --help
-
Show a specific help message and exit.
-
-
--sources SOURCE [SOURCE …]
-
See in the positional argument section above. In command line it is a space separated list.
-
-
--components COMPONENT [COMPONENT …]
-
See in the positional argument section above. In command line it is a space separated list.
-
Register project
Register a PVSS project.
PVSSBootstrapper registerProject PROJECT_PATH [-h] [--pmon-port N]
PVSSBootstrapper.registerProject(PROJECT_PATH
pmonPort=N)
-
PROJECT_PATH
-
Path of the project to register.
-
-
-h, --help
-
Show a specific help message and exit.
-
-
--pmon-port N or pmonPort=N
-
Set the port for pmon of the project to register (default: 0, don’t set).
-
Unregister project
Unregister a PVSS project.
If the project is running it will automatically stop it unless you use the dontStop option.
PVSSBootstrapper unregisterProject PROJECT_NAME [-h] [--dont-stop]
PVSSBootstrapper.unregisterProject(PROJECT_NAME
dontStop=True)
-
PROJECT_NAME
-
Name of the project to unregister.
-
-
-h, --help
-
Show a specific help message and exit.
-
-
--dont-stop or dontStop=True
-
Do not automatically stop the project if it is running (default: False).
-
Delete project
Delete a PVSS project (delete the files!).
If the project is running it will automatically stop it unless you use the dontStop option.
PVSSBootstrapper deleteProject PROJECT_NAME [-h] [--dont-stop]
PVSSBootstrapper.deleteProject(PROJECT_NAME
dontStop=True)
-
PROJECT_NAME
-
Name of the project to delete.
-
-
-h, --help
-
Show a specific help message and exit.
-
-
--dont-stop or dontStop=True
-
Do not automatically stop the project if it is running (default: False).
-
Is project registered?
Tell if a PVSS project is registered or not by its name.
In python, returns a boolean.
With the command line, first it writes on the output True or False. Then it sets the exit code to 0 for false and 1 for true. In bash, for instance, you can retrieve it with $?.
PVSSBootstrapper isProjectRegistered PROJECT_NAME [-h]
PVSSBootstrapper.isProjectRegistered(PROJECT_NAME)
-
PROJECT_NAME
-
Name of the project.
-
-
-h, --help
-
Show a specific help message and exit.
-
General purpose options
Some options can be used regardless of a Bootstrapper function.
With the command line tool they are valid only if you invoke them before the function name.
-
-h, --help
-
Show a help message and exit.
-
-
--pvss VERSION or pvss=VERSION
-
Use a specific PVSS version (default: the latest available).
-
-
-g, --debug or debug=True
-
Activate the debug flag (default: false).
-
Simplier scripts
TO COMPLETE
Bash script for Linux
TO COMPLETE
Batch script for Windows
TO COMPLETE