Introduction

Purpose

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.

Features

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

Requierements

  • 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.

Note
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.
Download

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

Install

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.

Note 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.

Creating a project
from PVSSBootstrapper import PVSSBootstrapper

try:
  PVSSBootstrapper.createProject('Path/To/Sandbox', 'MyTestProj', overwrite=True)
except PVSSBootstrapper.PVSSBootstrapperException as ex:
  print ex
Starting a project
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):

createMyTestProject.txt
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

Usage in command line
PVSSBootstrapper [-h] [--pvss VERSION] [-g]
                    {startProject,stopProject,stopAllProjects,registerProject,
                    unregisterProject,deleteProject,createProject,deployZip,
                    setComponentInstallationFolder,installComponent}
                    ...
Usage in Python
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

Optional arguments are documented in this section: General purpose options.

Table 1. Available sub-commands
Function Description Documentation

createProject

Create a PVSS project.

Create project reference

getProjectPath

Resolve the project path with a PVSS project name.

Get project path reference

listProjects

List all PVSS projects.

List projects reference

startProject

Start a PVSS project.

Start project reference

stopProject

Stop a PVSS project.

Stop project reference

stopAllProjects

Stop all PVSS projects.

Stop all projects reference

isProjectRunning

Is a PVSS project running?

Is project running reference

deployZip

Extract a Zip file inside a project.

Deploy Zip file reference

setComponentInstallationFolder

Set the folder in which the installation tool will install the components.

Set component installation folder reference

installComponent

Install one or many components.

Install component reference

registerProject

Register a PVSS project.

Register project reference

unregisterProject

Unregister a PVSS project.

Unregister project reference

deleteProject

Delete a PVSS project (delete the files!).

Delete project reference

isProjectRegistered

Is a PVSS project registered?

Is project registered reference

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.

Usage in command line
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]
Usage in Python
PVSSBootstrapper.createProject(INSTALL_PATH, PROJECT_NAME,
                               overwrite=True,
                               systemNumber=N, systemName=NAME,
                               pmonPort=N, dataPort=N,
                               eventPort=N, distPort=N)
Positional arguments

  • INSTALL_PATH

    • Directory where the project will be created.

  • PROJECT_NAME

    • The name of the project to create.

Optional arguments

  • -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.

Usage in command line
PVSSBootstrapper getProjectPath PROJECT_NAME [-h]
Usage in Python
PVSSBootstrapper.getProjectPath(PROJECT_NAME)
Positional argument

  • PROJECT_NAME

    • Name of the project to stop.

Optional arguments

  • -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.

Usage in command line
PVSSBootstrapper listProject [-h]
Usage in Python
PVSSBootstrapper.listProject()
Optional arguments

  • -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.

Usage in command line
PVSSBootstrapper startProject PROJECT
                                 [-h] [--restart]
                                 [--user USER] [--password PASSWORD]
                                 [--no-console] [--no-log-viewer]
                                 [--dont-register] [--dont-wait]
Usage in Python
PVSSBootstrapper.startProject(PROJECT,
                              restart=True,
                              user=USER, password=PASSWORD,
                              noConsole=True, noLogViewer=True,
                              dontRegister=True, dontWait=True)
Positional argument

  • PROJECT

    • Path or name of the project to start.

Optional arguments

  • -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.

Usage in command line
PVSSBootstrapper stopProject PROJECT_NAME [-h]
Usage in Python
PVSSBootstrapper.stopProject(PROJECT_NAME)
Positional argument

  • PROJECT_NAME

    • Name of the project to stop.

Optional arguments

  • -h, --help

    • Show a specific help message and exit.

Stop all projects

Stop all PVSS projects currently running on the machine.

Usage in command line
PVSSBootstrapper stopAllProjects [-h]
Usage in Python
PVSSBootstrapper.stopAllProjects()
Optional arguments

  • -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 $?.

Usage in command line
PVSSBootstrapper isProjectRunning PROJECT_NAME [-h]
Usage in Python
PVSSBootstrapper.isProjectRunning(PROJECT_NAME)
Positional argument

  • PROJECT_NAME

    • Name of the project.

Optional arguments

  • -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.

Usage in command line
PVSSBootstrapper deployZip PROJECT_NAME ZIP_FILE [-h]
Usage in Python
PVSSBootstrapper.deployZip(PROJECT_NAME, ZIP_FILE)
Positional argument

  • PROJECT_NAME

    • Name of the project where the Zip file will be extracted.

  • ZIP_FILE

    • Zip file to extract.

Optional arguments

  • -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 ../.

Usage in command line
PVSSBootstrapper setComponentInstallationFolder PROJECT_NAME FOLDER [-h]
Usage in Python
PVSSBootstrapper.setComponentInstallationFolder(PROJECT_NAME, FOLDER)
Positional argument

  • PROJECT_NAME

    • Name of the project where the Zip file will be extracted.

  • FOLDER

    • Folder where the components will be installed.

Optional arguments

  • -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.

Usage in command line
PVSSBootstrapper installComponent PROJECT_NAME
                                     [-h]
                                     [--sources SOURCE [SOURCE ...]]
                                     [--components COMPONENT [COMPONENT ...]]
Usage in Python
PVSSBootstrapper.installComponent(PROJECT_NAME, [SOURCE, ...], [COMPONENT, ...])
Positional argument

  • 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.

Optional arguments

  • -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.

Usage in command line
PVSSBootstrapper registerProject PROJECT_PATH [-h] [--pmon-port N]
Usage in Python
PVSSBootstrapper.registerProject(PROJECT_PATH
                                 pmonPort=N)
Positional argument

  • PROJECT_PATH

    • Path of the project to register.

Optional arguments

  • -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.

Usage in command line
PVSSBootstrapper unregisterProject PROJECT_NAME [-h] [--dont-stop]
Usage in Python
PVSSBootstrapper.unregisterProject(PROJECT_NAME
                                   dontStop=True)
Positional argument

  • PROJECT_NAME

    • Name of the project to unregister.

Optional arguments

  • -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.

Usage in command line
PVSSBootstrapper deleteProject PROJECT_NAME [-h] [--dont-stop]
Usage in Python
PVSSBootstrapper.deleteProject(PROJECT_NAME
                               dontStop=True)
Positional argument

  • PROJECT_NAME

    • Name of the project to delete.

Optional arguments

  • -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 $?.

Usage in command line
PVSSBootstrapper isProjectRegistered PROJECT_NAME [-h]
Usage in Python
PVSSBootstrapper.isProjectRegistered(PROJECT_NAME)
Positional argument

  • PROJECT_NAME

    • Name of the project.

Optional arguments

  • -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.

Optional arguments

  • -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