Arcanist User Guide: Customizing Lint, Unit Tests and Workflows

Phabricator User Documentation (Application User Guides)

Explains how to build new classes to control how Arcanist behaves.

This is a configuration guide that helps you set up advanced features. If you're just getting started, you don't need to look at this yet. Instead, start with the Arcanist User Guide.

Overview

Arcanist has some basic configuration options available in the .arcconfig file (see Arcanist User Guide: Configuring a New Project), but it can't handle everything. If you want to customize Arcanist at a deeper level, you need to build new classes. For instance:

• if you want to configure linters, or add new linters, you need to create a new class which extends ArcanistLintEngine.
• if you want to integrate with a unit testing framework, you need to create a new class which extends ArcanistUnitTestEngine.
• if you you want to change how workflows behave, or add new workflows, you need to create a new class which extends ArcanistConfiguration.

Arcanist works through a sort of dependency-injection approach. For example, Arcanist does not run lint rules by default, but you can set lint.engine in your .arcconfig to the name of a class which extends ArcanistLintEngine. When running from inside your project, Arcanist will load this class and call methods on it in order to run lint. To make this work, you need to do three things:

• actually write the class;
• add the library where the class exists to your .arcconfig;
• add the class name to your .arcconfig as the lint.engine, unit.engine, or arcanist_configuration.

Create a libphutil Library

If you haven't created a library for the class to live in yet, you need to do that first. Follow the instructions in Adding New Classes, then make the library loadable by adding it to your .arcconfig like this:

{
  // ...
  "load" : [
    // ...
    "/path/to/my/library", // Absolute path
    "support/arcanist",    // Relative path in this project
    // ...
  ]
  // ...
}

You can either specify an absolute path, or a path relative to the project root. When you run arc list --trace, you should see a message to the effect that it has loaded your library.

For debugging or testing, you can also run Arcanist with the --load-phutil-library flag:

arc --load-phutil-library=/path/to/library <command>

You can specify this flag more than once to load several libraries. Note that if you use this flag, Arcanist will ignore any libraries listed in .arcconfig.

Use the Class

This step is easy: just edit .arcconfig to specify your class name as the appropriate configuration value.

{
  // ...
  "lint.engine" : "CustomArcanistLintEngine",
  // ...
}

Now, when you run Arcanist in your project, it will invoke your class when appropriate.

For lint and unit tests, you can also use the --engine flag override the default engine:

arc lint --engine MyCustomArcanistLintEngine

This is mostly useful for debugging and testing.

Next Steps

• Learn how to reuse existing linters by reading Arcanist User Guide: Customizing Existing Linters.