Logo

Configuration Reference

Most deep analysis tools build the project as part of operating. Muse can detect the build system and a build target to identify the code and decide which analyzer should be applied. Alternatively, direct configuration of Muse is possible by writing and committing a .muse.toml file to your repository. Explicit configuration is not usually required unless custom compilation steps must be taken, such as using non-standard build targets or installing external library dependencies. This page describes the supported build systems and configuration options available to influence build, analysis, and general Muse operation on a per-repository basis.

In-Repo Options (The .muse.toml)

By default Muse will attempt to run all its analysts on a repository, generating reports from all analyses that succeed. The configuration file can be used to enabled or disabled analysis passes, specify the build system, and filter types of bugs reported. The file .muse.toml controls Muse’s behavior using the fields:

setup                   = <path to setup script>
build                   = ENV=<env> <command> [target]
important               = <exclusive list of issues to report back to user>
ignore                  = <list of issues never to report to the user>
tools                   = <infer | errorprone | eslint | hlint | findsecbugs >
customTools             = <list of user-provided tools conforming to a tool API>
allow                   = <list of users who's pull requests can trigger analysis>
jdk11                   = <true or false (defaults to false)>
androidVersion          = <the android SDK version number>
errorprone_bug_patterns = <list of bug patterns>
  • setup: A script that can perform pre-build configuration, such as installing tools (ex: apt install dependency) or libraries. The path should be either absolute or relative to the root of the repository. Refer to

  • build: A build script or command (overrides auto detection). Valid build commands include “make”, “gradlew”, “maven”, “autogen”, “configure”, “cmake”, and “gradle”.

    • Autogen implies ./autogen.sh ; ./configure ; make a la typical autotools workflow.
    • “configure” similarly starts one step later.
    • “gradlew” without an explicit target will try the assemble target.
    • You may set environment variables from the build line: build = "CC=gcc GXX=g++ CXX=g++ make"
  • important: A white list of issues considered important enough to report. If defined, only bugs of types that are in this list will ever be reported to the user. The values here match the bold faced header, aka issue “type”, seen on the reports.

  • ignore: The opposite of important, a blacklist of issues that should never be reported. Any issue in the ignore list is never reported to the user, even if it is marked important. For example, you can ignore ESLint’s no-empty message by specifying ignore = [ "no-empty" ].

  • tools: List of analysis tools to apply to the repository. By default each tool supported by Muse will be applied.

  • customTools: List of custom tools to run. This can run any manner of tool. For a basic example that can serve as a starting point for your own tool see the Custom Tools Section

  • allow: List of user names whose pull requests will cause analysis and result in comments being posted. The default behavior is to run muse on all pull requests regardless of author.

  • jdk11: A boolean field indicating use of OpenJDK11 instead of OpenJDK8.

  • androidVersion: The android SDK version number. This option is required for all android projects. Valid values are 27 and 28.

  • errorprone_bug_patterns: Use the provided, and only the provided, errorprone bug patterns. For example errorprone_bug_patterns = [ "ArrayEquals", "ArrayToString" ].

An actual configuration might look like:

setup     = ".muse/script_that_downloads_deps.sh"
build     = "gradlew assemble"
# We only care about NULL_DEREFERENCE (from Infer)
# and no-extra-boolean-cast (from ESLint)
important = ["NULL_DEREFERENCE", "no-extra-boolean-cast"]
# Only run infer and eslint (do not run errorprone, hlint, findsecbugs)
tools = [ "infer", "eslint" ]
# Only analyze and post responses to PRs from developers with these usernames
allow = [ "jill", "dave", "shawn" ]
jdk11 = false

The file and all fields are optional. By default, Muse will attempt to infer appropriate values for any setting that isn’t specified in the file.

Build System Support

Muse analyses look for build system files on the repository root and through all the subdirectories. A build system is necessary for Muse to learn which files are appropriate to analyze, which dependencies (libraries and class paths) to leverage, and which compilation flags are appropriate. The supported build systems include:

  • gradlew:
    • Description: Muse will use the gradle wrapper
    • Condition: When a gradlew file is found.
    • Command line equivalent: ./gradlew assemble
  • gradle:
    • Description: Muse will use the Gradle build system
    • Condition: When a build.gradle file is found.
    • Command line equivalent: gradle assemble
  • CompDB:
    • Description: Muse will read compile commands from a JSON file.
    • Condition: When a compile_commands.json file exists.
    • Command line equivalent: Sequentially invoking the commands with arguments and files specified in the JSON file.
  • Maven:
    • Description: Muse will use Maven
    • Condition: When a pom.xml file is found.
    • Command line equivalent: mvn compile -B
  • Make:
    • Description: Muse will use make.
    • Condition: When a {M,m}akefile file is found
  • Autotools:
    • Description: Muse will invoke the common GNU AutoTools of autogen.sh and configure to try and produce a Makefile.
    • Condition: Used when autogen.sh or configure files are found.
    • Command line equivalent: ./autogen.sh || ./configure && make
  • Compilation database:
    • Description: Muse will us the individual compilation commands and arguments specified by a compilation database.
    • Condition: Used when compile_commands.json is found.

Subprojects

Muse supports nested subprojects and projects not at the root level. This lets you easily build Muse into your monolithic repos and lets you specify entirely different build systems for different parts of your code. To set this up, each subproject needs its own Muse configuration file in the root directory of that subproject. This configuration file should use the same format as before, and in it you can configure specific tools and build systems to use for your subproject.

The top-level .muse.toml file can still optionally exist and can be used to build a top-level project. Additionally, this top-level configuration file is the only place you should put an allow list. Because the allowlist is global the allow field is only read from the top-level configuration file.

The directory structure might look something like this:

.muse.toml

project_a/
project_a/.muse.toml
project_a/Makefile
project_a/main.c

project_b/
project_b/.muse.toml
project_b/Makefile
project_b/main.c

Muse will then automatically run on both Project A and Project B.

APIs for Custom Tools

Muse supports arbitrary tools for users to extend and customize the types of comments made on pull requests. The customizations can either be a file path or HTTPS URL to a script followed by arguments. Here are some example configurations and links to the supported APIs so you can add your own checks.

Example Extended Checks - Fixing the FIXME

Let’s say you have a repository that you wish to keep clean of crufty code comments such as TODO, XXX, and FIXME. Add to the .muse.toml file:

customTools =  ["https://docs.muse.dev/scripts/check-common-comments.sh"]

There is no magic in the URL - you can download that script, change it, re-host it on your own domain, and have Muse run checks of your own design. The check-common-comments script will grep through your source code and report any instance of the offending strings.

In many cases the script might be project-specific and can be hosted in the repository. In this case you might place the file .muse/my_script.sh in your repository and have a tools line of:

customTools = [ ".muse/my_script.sh" ]

Example Extended Checks - ShellCheck and PMD

Let’s look at two more examples. The first is a Java analysis tool PMD and the second is a shell script checker ShellCheck.

The PMD script is parameterized by the rule set so we’ll pass in an argument. Our ShellCheck support script hard codes some simple assumptions and does not consider arguments. We further disable the built-in tools, yielding a .muse.toml file of:

tools = [ ]
customTools = [ "https://docs.muse.dev/scripts/pmd.sh rulesets/java/quickstart.xml"
              , "https://docs.muse.dev/scripts/shellcheck.sh"
              ]

The hosted example scripts are use binaries of pmd and shellcheck that are already on the image - the scripts just run the tool then translate the resulting JSON. If your preferred tool isn’t installed consider specifying a installation script in the setup configuration field to adjust the environment first.

Extended Tooling with Custom or Community-provided Tools

The above configuration shows how to invoke an existing tool. These tools all must conform to one of Muse’s APIs. Please refer to our tool API for information necessary to build a tool.