Run.jl

Run

Run.jl provides functions to run tests or build documentation in an isolated environment. See more in the documentation.

Features

• Simpler CI setup (.travis.yml, .gitlab-ci.yml, etc.)
• Isolated and activatable sub-environments for Julia < 1.2.
• Reproducible runs not only for test but also for any sub-projects (docs, benchmarks, etc.)
• Finer Julia options (e.g., Run.test(fast=true) to run tests faster by minimizing JIT compilation.)

Examples

.travis.yml

To use Run.test to run tests in Travis CI, add the following snippet in .travis.yml.

before_install:
  - unset JULIA_PROJECT
  - julia -e 'using Pkg; pkg"add https://github.com/tkf/Run.jl"'
install:
  - julia -e 'using Run; Run.prepare_test()'
script:
  - julia -e 'using Run; Run.test()'
after_success:
  - julia -e 'using Run; Run.after_success_test()'
jobs:
  include:
    - stage: Documentation
      install:
        - julia -e 'using Run; Run.prepare_docs()'
      script:
        - julia -e 'using Run; Run.docs()'
      after_success: skip

Side notes:

• Run.prepare_test() and Run.prepare_docs() are not required but it is a good idea to separate installation and test.
• The test log can be minimized by passing prepare=false to Run.test.

.gitlab-ci.yml

.template:
  image: julia
  before_script:
    - julia -e 'using Pkg; pkg"add https://github.com/tkf/Run.jl"'

test:
  extends: .template
  script:
    - julia -e 'using Run; Run.test()'

pages:
  extends: .template
  stage: deploy
  script:
    - julia -e 'using Run; Run.docs()'
    - mv docs/build public
  artifacts:
    paths:
      - public
  only:
    - master

Run.script(path; <keyword arguments>)

Run Julia script at path after activating $path/Project.toml.

See also Run.test and Run.docs.

Keyword Arguments

• project::String: Project to be used instead of $path/../Project.toml.
• parentproject::String: Project to be added to project if it does not have corresponding manifest file.
• fast::Bool = false: Try to run it faster (more precisely, skip prepare and pass --compile=min option to Julia subprocess.)
• prepare::Bool = !fast: Call Run.prepare_test if true (default).
• compiled_modules::Union{Bool, Nothing} = nothing: Use --compiled-modules=yes (--compiled-modules=no) option if true (false). If false, it also skips precompilation in the preparation phase.
• precompile::Bool = (compiled_modules != false): Precompile project before running script.
• strict::Bool = true: Do not include the default environment in the load path (more precisely, set the environment variable JULIA_LOAD_PATH=@).
• code_coverage::Bool = false: Control --code-coverage option.
• check_bounds::Union{Nothing, Bool} = nothing: Control --check-bounds option. nothing means to inherit the option specified for the current Julia session.
• depwarn::Union{Nothing, Bool, Symbol} = nothing: Use --depwarn setting of the current process if nothing (default). Set --depwarn=yes if true or --depwarn=no if false. A symbol value is passed as --depwarn value. So, passing :error sets --depwarn=error.
• xfail::bool = false: If failure is expected.
• exitcodes::AbstractVector{<:Integer} = xfail ? [1] : [0]: List of allowed exit codes.
• Other keywords are passed to Run.prepare_test.

Run.test(path="test"; <keyword arguments>)

Run $path/runtests.jl after activating $path/Project.toml. It simply calls Run.script with default keyword arguments code_coverage = true, check_bounds = true, and depwarn = true.

path can also be a path to a script file.

See also Run.script and Run.

Run.docs(path="docs"; <keyword arguments>)

Run $path/make.jl after activating $path/Project.toml. It simply calls Run.script.

path can also be a path to a script file.

Run.prepare(path::AbstractString; precompile, parentproject)

Instantiate $path/Project.toml. It also devs the project in the parent directory of path into $path/Project.toml if $path/Manifest.toml does not exist.

Keyword Arguments

• precompile::Bool = true: Precompile the project if true (default).
• parentproject::AbstractString: Path to parent project. Default to parent directory of path.

Run.prepare_test(path="test"; precompile)

It is an alias of Run.prepare("test").

Run.prepare_docs(path="docs"; precompile)

It is an alias of Run.prepare("docs").

Run.migratetest(path=".")

Migrate test setup from [targets] in $path/Project.toml to $path/test/Project.toml.