@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
1@title Arcanist User Guide: Customizing Lint, Unit Tests and Workflows
2@group userguide
3
4Explains how to build new classes to control how Arcanist behaves.
5
6This is a configuration guide that helps you set up advanced features. If you're
7just getting started, you don't need to look at this yet. Instead, start with
8the @{article:Arcanist User Guide}.
9
10= Overview =
11
12Arcanist has some basic configuration options available in the `.arcconfig`
13file (see @{article:Arcanist User Guide: Configuring a New Project}), but it
14can't handle everything. If you want to customize Arcanist at a deeper level,
15you need to build new classes. For instance:
16
17 - if you want to configure linters, or add new linters, you need to create a
18 new class which extends @{class@arcanist:ArcanistLintEngine}.
19 - if you want to integrate with a unit testing framework, you need to create a
20 new class which extends @{class@arcanist:ArcanistUnitTestEngine}.
21 - if you you want to change how workflows behave, or add new workflows, you
22 need to create a new class which extends
23 @{class@arcanist:ArcanistConfiguration}.
24
25Arcanist works through a sort of dependency-injection approach. For example,
26Arcanist does not run lint rules by default, but you can set `lint.engine`
27in your `.arcconfig` to the name of a class which extends
28@{class@arcanist:ArcanistLintEngine}. When running from inside your project,
29Arcanist will load this class and call methods on it in order to run lint. To
30make this work, you need to do three things:
31
32 - actually write the class;
33 - add the library where the class exists to your `.arcconfig`;
34 - add the class name to your `.arcconfig` as the **lint.engine**,
35 **unit.engine**, or **arcanist_configuration**.
36
37= Create a Library =
38
39If you haven't created a library for the class to live in yet, you need to do
40that first. Follow the instructions in
41@{article@contrib:Adding New Classes}, then make the library loadable by
42adding it to your `.arcconfig` like this:
43
44 {
45 // ...
46 "load" : [
47 // ...
48 "/path/to/my/library", // Absolute path
49 "support/arcanist", // Relative path in this project
50 // ...
51 ]
52 // ...
53 }
54
55You can either specify an absolute path, or a path relative to the project root.
56When you run `arc list --trace`, you should see a message to the effect that
57it has loaded your library.
58
59For debugging or testing, you can also run Arcanist with the
60`--load-phutil-library` flag:
61
62 arc --load-phutil-library=/path/to/library <command>
63
64You can specify this flag more than once to load several libraries. Note that
65if you use this flag, Arcanist will ignore any libraries listed in
66`.arcconfig`.
67
68= Use the Class =
69
70This step is easy: just edit `.arcconfig` to specify your class name as
71the appropriate configuration value.
72
73 {
74 // ...
75 "lint.engine" : "CustomArcanistLintEngine",
76 // ...
77 }
78
79Now, when you run Arcanist in your project, it will invoke your class when
80appropriate.
81
82For lint and unit tests, you can also use the `--engine` flag override the
83default engine:
84
85 arc lint --engine MyCustomArcanistLintEngine
86
87This is mostly useful for debugging and testing.
88
89= Next Steps =
90
91 - Learn how to reuse existing linters by reading
92 @{article:Arcanist User Guide: Customizing Existing Linters}.