Command line¶
Main script of project Universum is universum.py.
All command-line parameters, general and module-related, are passed to this main script.
Note
Most of command-line parameters can be replaced by setting up corresponding environment variables (see ‘env’ comment in descriptions)
Universum 0.18.6-python2.7.6
usage: universum [-h] [--version] [--build-only-latest] [--no-diff]
[--artifact-dir ARTIFACT_DIR] [--no-archive]
[--project-root PROJECT_ROOT]
[--server-type {tc,jenkins,local}]
[--tc-server TEAMCITY_SERVER] [--tc-build-id BUILD_ID]
[--tc-configuration-id CONFIGURATION_ID]
[--tc-auth-user-id TC_USER] [--tc-auth-passwd TC_PASSWD]
[--jenkins-build-url BUILD_URL] [--report-build-start]
[--report-build-success] [--report-only-fails]
[--report-no-vote] [--out-type {tc,term,jenkins}]
[--out {console,file}] [--config CONFIG_PATH]
[--filter LAUNCHER.STEP_FILTER] [--report-to-review]
[--vcs-type VCS_TYPE] [--git-checkout-id GIT_CHECKOUT_ID]
[--git-cherry-pick-id GIT_CHERRYPICK_ID [GIT_CHERRYPICK_ID ...]]
[--git-repo GIT_REPO] [--git-refspec GIT_REFSPEC]
[--github-token GITHUB_TOKEN]
[--github-check-name GITHUB_CHECK_NAME]
[--github-check-id GITHUB_CHECK_ID]
[--github-api-url GITHUB_API_URL]
[--file-source-dir SOURCE_DIR] [--p4-client P4CLIENT]
[--p4-sync SYNC_CHANGELIST [SYNC_CHANGELIST ...]]
[--p4-shelve SHELVE_CHANGELIST [SHELVE_CHANGELIST ...]]
[--p4-force-clean] [--p4-project-depot-path P4_PATH]
[--p4-mappings P4_MAPPINGS [P4_MAPPINGS ...]]
[--p4-port P4PORT] [--p4-user P4USER]
[--p4-password P4PASSWD] [--swarm-server-url SWARM_SERVER]
[--swarm-review-id REVIEW] [--swarm-change SWARM_CHANGELIST]
[--swarm-pass-link PASS] [--swarm-fail-link FAIL]
{poll,submit,nonci} ...
Named Arguments¶
| --version | |
| Display product name & version instead of launching. | |
| --build-only-latest | |
Skip build if review version isn’t latest Default: False | |
| --no-diff | |
Only applies to build steps where Default: False | |
Artifact collection¶
Parameters of archiving and collecting of build artifacts
| --artifact-dir, -ad | |
Directory to collect artifacts to. Default is ‘artifacts’ Environment variable: $ARTIFACT_DIR | |
| --no-archive | |
By default all directories noted as artifacts are copied as .zip archives. This option turn archiving off to copy bare directories to artifact directory Default: False | |
Source files¶
Parameters determining the processing of repository files
| --project-root, -pr | |
Temporary directory to copy sources to. Default is ‘temp’ Environment variable: $PROJECT_ROOT | |
| --report-to-review | |
Perform test build for code review system (e.g. Gerrit or Swarm). Default: False | |
| --vcs-type, -vt | |
Possible choices: none, p4, git, gerrit, github Select repository type to download sources from: Perforce (‘p4’), Git (‘git’), Gerrit (‘gerrit’), GitHub (‘github’) or a local directory (‘none’). Gerrit uses Git parameters. Each VCS type has its own settings. Environment variable: $VCS_TYPE | |
Automation server¶
Automation server options
| --server-type, -st | |
Possible choices: tc, jenkins, local Type of environment to refer to (tc - TeamCity, jenkins - Jenkins, local - user local terminal). TeamCity and Jenkins environment is detected automatically when launched on build agent | |
TeamCity variables¶
TeamCity-specific parameters
| --tc-server, -ts | |
TeamCity server URL Environment variable: $TEAMCITY_SERVER | |
| --tc-build-id, -tbi | |
teamcity.build.id Environment variable: $BUILD_ID | |
| --tc-configuration-id, -tci | |
system.teamcity.buildType.id Environment variable: $CONFIGURATION_ID | |
| --tc-auth-user-id, -tcu | |
system.teamcity.auth.userId Environment variable: $TC_USER | |
| --tc-auth-passwd, -tcp | |
system.teamcity.auth.password Environment variable: $TC_PASSWD | |
Jenkins variables¶
Jenkins-specific parameters
| --jenkins-build-url, -jbu | |
Link to build on Jenkins (automatically set by Jenkins) Environment variable: $BUILD_URL | |
Result reporting¶
Build results collecting and publishing parameters
| --report-build-start, -rst | |
Send additional comment to review system on build started (with link to log) Default: False | |
| --report-build-success, -rsu | |
Send comment to review system on build success (in addition to vote up) Default: False | |
| --report-only-fails, -rof | |
Include only the list of failed steps to reporting comments Default: False | |
| --report-no-vote, -rnv | |
Do not vote up/down review depending on result Default: False | |
Output¶
Log appearance parameters
| --out-type, -ot | |
Possible choices: tc, term, jenkins Type of output to produce (tc - TeamCity, jenkins - Jenkins, term - terminal). TeamCity environment is detected automatically when launched on build agent. | |
| --out, -o | |
Possible choices: console, file Define whether to print build logs to console or file. Log file names are generated based on the names of build steps. By default, logs are printed to console when the build is launched on Jenkins or TeamCity agent | |
Configuration execution¶
External command launching and reporting parameters
| --config, -cfg | |
Path to project config file (example: -cfg=my/prject/my_conf.py). Mandatory parameter. Environment variable: $CONFIG_PATH | |
| --filter, -f | |
Allows to filter which steps to execute during launch.
String value representing single filter or a set of filters separated by ‘:’.
To define exclude pattern use ‘!’ symbol at the beginning of the pattern.
A Universum step match specified pattern when ‘filter’ is a substring of step ‘name’.
This functionality is similar to ‘boosttest’ and ‘gtest’ filtering, except special characters
(like ‘*’, ‘?’, etc.) are ignored.
Examples:
* -f=’run test’ - run only steps that contain ‘run test’ substring in their names
* -f=’!run test’ - run all steps except those containing ‘run test’ substring in their
names
* -f=’test 1:test 2’ - run all steps with ‘test 1’ OR ‘test 2’ substring in their names
* -f=’test 1:!unit test 1’ - run all steps with ‘test 1’ substring in their names except those
containing ‘unit test 1’
| |
Git¶
| --git-checkout-id, -gco | |
A commit ID to checkout. Could be exact commit hash, or branch name, or tag, etc. Environment variable: $GIT_CHECKOUT_ID | |
| --git-cherry-pick-id, -gcp | |
List of commit IDs to be cherry-picked, separated by comma. ‘–git-cherry-pick-id’ can be added to the command line several times Environment variable: $GIT_CHERRYPICK_ID | |
| --git-repo, -gr | |
See your project home page for exact repository identifier, passed to ‘git clone’. If using SSH, ‘–git-repo’ format is ‘ssh://user@server:port/detailed/path’ Environment variable: $GIT_REPO | |
| --git-refspec, -grs | |
Any additional refspec to be fetched Environment variable: $GIT_REFSPEC | |
GitHub¶
GitHub repository settings
| --github-token, -ght | |
GitHub API token; for details see https://developer.github.com/v3/oauth_authorizations/ Environment variable: $GITHUB_TOKEN | |
| --github-check-name, -ghc | |
The name of Github check run Environment variable: $GITHUB_CHECK_NAME Default: “Universum check” | |
| --github-check-id, -ghi | |
Github check run ID Environment variable: $GITHUB_CHECK_ID | |
| --github-api-url, -gha | |
API URL for integration Environment variable: $GITHUB_API_URL Default: “https://api.github.com/” | |
Local files¶
Parameters for file settings in case of no VCS used
| --file-source-dir, -fsd | |
A local folder for project sources to be copied from. This option is only needed when ‘–driver-type’ is set to ‘none’ Environment variable: $SOURCE_DIR | |
Perforce¶
| --p4-client, -p4c | |
P4 client (workspace) name to be created. Use ‘–p4-force-clean’ option to delete this client while finalizing Environment variable: $P4CLIENT | |
| --p4-sync, -p4h | |
Sync (head) CL(s). Just a number will be interpreted as united CL for all added VCS roots. To add a sync CL for specific depot/workspace location, write location in the same format as in P4_MAPPINGS with ‘@<CL number>’ in the end, e.g. ‘//DEV/Solution/MyProject/…@1234567’. To specify more than one sync CL for several locations, add ‘–p4-sync’ several times or split them with comma Environment variable: $SYNC_CHANGELIST | |
| --p4-shelve, -p4s | |
List of shelve CLs to be applied, separated by comma. –p4-shelve can be added to the command line several times. Also shelve CLs can be specified via additional environment variables: SHELVE_CHANGELIST_1..5 Environment variable: $SHELVE_CHANGELIST | |
| --p4-force-clean | |
Revert all vcs within ‘–p4-client’ and delete the workspace. Mandatory for CI environment, otherwise use with caution Default: False | |
| --p4-project-depot-path, -p4d | |
Depot path to get sources from (starts with ‘//’, ends with ‘/…’Only supports one path. Cannot be used with ‘–p4-mappings’ option Environment variable: $P4_PATH | |
| --p4-mappings, -p4m | |
P4 mappings. Cannot be used with ‘–p4-project-depot-path’ option. Use the following format: ‘//depot/path/… /local/path/…’, where the right half is the same as in real P4 mappings, but without client name. Just start from client root with one slash. For more than one add several times or split with ‘,’ character Environment variable: $P4_MAPPINGS | |
| --p4-port, -p4p | |
P4 port (e.g. ‘myhost.net:1666’) Environment variable: $P4PORT | |
| --p4-user, -p4u | |
P4 user name Environment variable: $P4USER | |
| --p4-password, -p4P | |
P4 password Environment variable: $P4PASSWD | |
Swarm¶
Parameters for performing a test run for pre-commit review
| --swarm-server-url, -ssu | |
Swarm server URL; is used for additional interaction such as voting for the review Environment variable: $SWARM_SERVER | |
| --swarm-review-id, -sre | |
Swarm review number; is sent by Swarm triggering link as ‘{review}’ Environment variable: $REVIEW | |
| --swarm-change, -sch | |
Swarm change list to unshelve; is sent by Swarm triggering link as ‘{change}’ Environment variable: $SWARM_CHANGELIST | |
| --swarm-pass-link, -spl | |
Swarm ‘success’ link; is sent by Swarm triggering link as ‘{pass}’ Environment variable: $PASS | |
| --swarm-fail-link, -sfl | |
Swarm ‘fail’ link; is sent by Swarm triggering link as ‘{fail}’ Environment variable: $FAIL | |
Additional commands¶
| {poll,submit,nonci} | |