@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 Diffusion User Guide: Symbol Indexes
2@group userguide
3
4Guide to configuring and using the symbol index.
5
6= Overview =
7
8Phorge can maintain a symbol index, which keeps track of where classes
9and functions are defined in the codebase. Once you set up indexing, you can
10use the index to do things like:
11
12 - jump to symbol definitions from Differential code reviews and Diffusion
13 code browsing by ctrl-clicking (cmd-click on Mac) symbols
14 - search for symbols from the quick-search
15 - let the IRC bot answer questions like "Where is SomeClass?"
16
17NOTE: Because this feature depends on the syntax highlighter, it will work
18better for some languages than others. It currently works fairly well for PHP,
19but your mileage may vary for other languages.
20
21= Populating the Index =
22
23To populate the index, you need to write a script which identifies symbols in
24your codebase and set up a cronjob which pipes its output to:
25
26 ./scripts/symbols/import_repository_symbols.php
27
28Phorge includes a script which can identify symbols in PHP projects:
29
30 ./scripts/symbols/generate_php_symbols.php
31
32Phorge also includes a script which can identify symbols in any
33programming language that has classes and/or functions, and is supported by
34Exuberant Ctags (https://ctags.sourceforge.net):
35
36 ./scripts/symbols/generate_ctags_symbols.php
37
38If you want to identify symbols from another language, you need to write a
39script which can export them (for example, maybe by parsing a `ctags` file).
40
41The output format of the script should be one symbol per line:
42
43 <context> <name> <type> <lang> <line> <path>
44
45For example:
46
47 ExampleClass exampleMethod function php 13 /src/classes/ExampleClass.php
48
49Context is, broadly speaking, the scope or namespace where the symbol is
50defined. For object-oriented languages, this is probably a class name. The
51symbols with that context are class constants, methods, properties, nested
52classes, etc. When printing symbols without a context (those that are defined
53globally, for instance), the `<context>` field should be empty (that is, the
54line should start with a space).
55
56Your script should enumerate all the symbols in your project, and provide paths
57from the project root (where ".arcconfig" is) beginning with a "/".
58
59You can look at `generate_php_symbols.php` for an example of how you might
60write such a script, and run this command to see its output:
61
62 $ cd phorge/
63 $ find . -type f -name '*.php' | ./scripts/symbols/generate_php_symbols.php
64
65To actually build the symbol index, pipe this data to the
66`import_repository_symbols.php` script, providing the repository callsign:
67
68 $ ./scripts/symbols/import_repository_symbols.php REPO < symbols_data
69
70Then just set up a cronjob to run that however often you like.
71
72You can test that the import worked by querying for symbols using the Conduit
73method `diffusion.findsymbols`. Some features (like that method, and the
74IRC bot integration) will start working immediately. Others will require more
75configuration.
76
77= Advanced Configuration =
78
79You can configure some more options by going to {nav Diffusion > (Select
80 repository) > Edit Repository > Edit Symbols}, and filling out these fields:
81
82 - **Indexed Languages**: Fill in all the languages you've built indexes for.
83 You can leave this blank for "All languages".
84 - **Uses Symbols From**: If this project depends on other repositories, add
85 the other repositories which symbols should be looked for here. For example,
86 Phorge lists "Arcanist" because it uses classes and functions defined
87 in `arcanist/`.
88
89== External Symbols ==
90
91By @{article@contrib:Adding New Classes}, you can teach Phorge
92about symbols from the outside world.
93Extend @{class:DiffusionExternalSymbolsSource}; Once loaded, your new
94implementation will be used any time a symbol is queried.
95
96See @{class:DiffusionPhpExternalSymbolsSource} and
97@{class:DiffusionPythonExternalSymbolsSource} for example implementations.