Voyager's main purpose is to help extract data from software systems in a unified way. It runs a suit of configurable instruments according to a mission configuration.
Please take a look at how to configure and run Voyager below.
# The name of the mission *required
mission:
# The path to the target folder.
# The target folder should contain all repositories *required
target:
# A map of instrument names to commands and parameters.
# When 'runsAll' is false the mission will run only the instruments
# with the commands declared here, in this order.
instruments:
# The name of the instrument as declared in instrument.yml
My Instrument:
# The id of the thread on which to run the instrument
# Instruments on the same thread will run in the order they appear in this file
# instruments on the default thread, 0, will run separately after all other threads are completed
# Integer, defaults to 0
thread:
# The list of commands to run. Names as declared in instrument.yml
# If empty or not specified, voyager will run all commands from the instrument
commands:
# A map of parameter name to value
parameters:
# A special parameter that overrides the instruments setting to run on the
# target directory or on all the projects within the target
# Values: onEach, once, never
run:
# A map of environment variables, name to value, for voyager missions
# overwrites the variables from global config, instrument and command
environment:
# Path to the directory containing the instruments
# Default: ./instruments
instrumentsDir:
# Path to the result archive file
# Default: ./${mission}-voyager-results.zip
resultsPath:Example
mission: Git information gathering
target: /home/projects
instruments:
Git log:
commands:
- git log
parameters:
branch: mainThe global config if needed should be located at ./.config.yml and have the following structure
# Specifies if voyager should run the instruments and commands according to the mission
# or should it run all found instruments with all commands
# default true
runsAll:
# A map of runtime name to a path that will be added to the PATH env variable
# for voyager missions
runtimes:
# A map of environment variables, name to value, for voyager missions
# overrides values defined in instrument and command environments
environment:
# A default value for the instruments directory
# Default: ./instruments
instrumentsDir:Example
runsAll: false
runtimes:
java-11: environments/jdk-11.0.10/bin
python-3: environments/python-3.9.2-embed-amd64
node-14: environments/node-v14.16.0-win-x64
environment:
LINE_THRESHOLD: 3
instrumentsDir: ./mySpecialInstrumentsAn instrument is a list of configurable commands that should be run in an order on the target folder or on each project folder separately. It may also declare some result folders and files that will be packaged in the mission's data container.
By definition an instrument is a directory containing an instrument.yml file. All instrument directories should be located in the instrument's directory.
# The name of the instrument *required
name:
# Specifies if the instrument should run on the target directory or
# on all the projects within the target (once / onEach / never)
# Default: once
run:
# List of directories and file globs that should be added to the
# mission's data container
results:
# The path of the directory relative to . *required
- dir:
# The list of globs. Matching files are included in the data-container
files:
# List of declared commands
commands:
# The name of the command *required
- name:
# The command for windows systems
win:
# The command for unix based systems
unix:
# A map of name to value that will be added to
# the environment variables for this command
# overrides instrument environment variables
environment:
# The working directory for the command
# Default: ${instrument} the instrument's path
dir:
# A map of name to value that will be added to
# the environment variables for all commands of this instrument
environment:
# The map of parameters to be used in the configuration
# Voyager defined parameters:
# instrument: the path to the instrument's directory
# repo: the path to the current analysis directory (target/project)
# repoName: the name of the current analysis directory (target/project)
parameters:Example
name: Git log
run: onEach
results:
- dir: ${instrument}/results
files:
- "*.git"
commands:
- name: git log
win: git log > "${instrument}/results/${repoName}.git"
unix: git log > "${instrument}/results/${repoName}.git"
dir: ${repo}If the mission is in the default location ./mission.yml then you can run voyager with java -jar dx-voyager.jar
, voyager.sh or voyager.bat
Otherwise, run voyager using voyager.sh <path/to/mission/file>
If the instruments are not in the default location ./instruments then specify the instrumentsDir in mission.yml
The results declared by the instruments will be packaged in ./data-container.zip
voyager.sh doctor or voyager.sh doctor /path/to/doctor.yml
This command is used to verify the versions for the needed runtimes.
Example
versions:
-
# The name of the runtime to be checked
- name: Java
# The minimum version required for the runtime
min: 15
# The command to get the response containing the version
win: java -version
# The command to get the response containing the version
unix: java -version
# The regex patterns containing the version group
# used to match the output of the command
match:
- java version "(?<version>.+)".*
- (?i)openjdk(?-i) version "(?<version>.+)"
- name: Python
min: 3.8
win: python -V
unix: python -V
match:
- Python (?<version>.+)
- name: Node
min: 12
win: node -v
unix: node -v
match:
- v(?<version>.+)
voyager.sh version
voyager.sh clean or voyager.sh clean my-mission.yml
This command is used to clean the results from previous runs, in case of an interrupted mission