Changeset View
Changeset View
Standalone View
Standalone View
src/docs/user/userguide/diffusion_symbols.diviner
@title Diffusion User Guide: Symbol Indexes | @title Diffusion User Guide: Symbol Indexes | ||||
@group userguide | @group userguide | ||||
Guide to configuring and using the symbol index. | Guide to configuring and using the symbol index. | ||||
= Overview = | = Overview = | ||||
Phabricator can maintain a symbol index, which keeps track of where classes | Phorge can maintain a symbol index, which keeps track of where classes | ||||
and functions are defined in the codebase. Once you set up indexing, you can | and functions are defined in the codebase. Once you set up indexing, you can | ||||
use the index to do things like: | use the index to do things like: | ||||
- jump to symbol definitions from Differential code reviews and Diffusion | - jump to symbol definitions from Differential code reviews and Diffusion | ||||
code browsing by ctrl-clicking (cmd-click on Mac) symbols | code browsing by ctrl-clicking (cmd-click on Mac) symbols | ||||
- search for symbols from the quick-search | - search for symbols from the quick-search | ||||
- let the IRC bot answer questions like "Where is SomeClass?" | - let the IRC bot answer questions like "Where is SomeClass?" | ||||
NOTE: Because this feature depends on the syntax highlighter, it will work | NOTE: Because this feature depends on the syntax highlighter, it will work | ||||
better for some languages than others. It currently works fairly well for PHP, | better for some languages than others. It currently works fairly well for PHP, | ||||
but your mileage may vary for other languages. | but your mileage may vary for other languages. | ||||
= Populating the Index = | = Populating the Index = | ||||
To populate the index, you need to write a script which identifies symbols in | To populate the index, you need to write a script which identifies symbols in | ||||
your codebase and set up a cronjob which pipes its output to: | your codebase and set up a cronjob which pipes its output to: | ||||
./scripts/symbols/import_repository_symbols.php | ./scripts/symbols/import_repository_symbols.php | ||||
Phabricator includes a script which can identify symbols in PHP projects: | Phorge includes a script which can identify symbols in PHP projects: | ||||
./scripts/symbols/generate_php_symbols.php | ./scripts/symbols/generate_php_symbols.php | ||||
Phabricator also includes a script which can identify symbols in any | Phorge also includes a script which can identify symbols in any | ||||
programming language that has classes and/or functions, and is supported by | programming language that has classes and/or functions, and is supported by | ||||
Exuberant Ctags (http://ctags.sourceforge.net): | Exuberant Ctags (http://ctags.sourceforge.net): | ||||
./scripts/symbols/generate_ctags_symbols.php | ./scripts/symbols/generate_ctags_symbols.php | ||||
If you want to identify symbols from another language, you need to write a | If you want to identify symbols from another language, you need to write a | ||||
script which can export them (for example, maybe by parsing a `ctags` file). | script which can export them (for example, maybe by parsing a `ctags` file). | ||||
Show All 13 Lines | |||||
line should start with a space). | line should start with a space). | ||||
Your script should enumerate all the symbols in your project, and provide paths | Your script should enumerate all the symbols in your project, and provide paths | ||||
from the project root (where ".arcconfig" is) beginning with a "/". | from the project root (where ".arcconfig" is) beginning with a "/". | ||||
You can look at `generate_php_symbols.php` for an example of how you might | You can look at `generate_php_symbols.php` for an example of how you might | ||||
write such a script, and run this command to see its output: | write such a script, and run this command to see its output: | ||||
$ cd phabricator/ | $ cd phorge/ | ||||
$ find . -type f -name '*.php' | ./scripts/symbols/generate_php_symbols.php | $ find . -type f -name '*.php' | ./scripts/symbols/generate_php_symbols.php | ||||
To actually build the symbol index, pipe this data to the | To actually build the symbol index, pipe this data to the | ||||
`import_repository_symbols.php` script, providing the repository callsign: | `import_repository_symbols.php` script, providing the repository callsign: | ||||
$ ./scripts/symbols/import_repository_symbols.php REPO < symbols_data | $ ./scripts/symbols/import_repository_symbols.php REPO < symbols_data | ||||
Then just set up a cronjob to run that however often you like. | Then just set up a cronjob to run that however often you like. | ||||
You can test that the import worked by querying for symbols using the Conduit | You can test that the import worked by querying for symbols using the Conduit | ||||
method `diffusion.findsymbols`. Some features (like that method, and the | method `diffusion.findsymbols`. Some features (like that method, and the | ||||
IRC bot integration) will start working immediately. Others will require more | IRC bot integration) will start working immediately. Others will require more | ||||
configuration. | configuration. | ||||
= Advanced Configuration = | = Advanced Configuration = | ||||
You can configure some more options by going to {nav Diffusion > (Select | You can configure some more options by going to {nav Diffusion > (Select | ||||
repository) > Edit Repository > Edit Symbols}, and filling out these fields: | repository) > Edit Repository > Edit Symbols}, and filling out these fields: | ||||
- **Indexed Languages**: Fill in all the languages you've built indexes for. | - **Indexed Languages**: Fill in all the languages you've built indexes for. | ||||
You can leave this blank for "All languages". | You can leave this blank for "All languages". | ||||
- **Uses Symbols From**: If this project depends on other repositories, add | - **Uses Symbols From**: If this project depends on other repositories, add | ||||
the other repositories which symbols should be looked for here. For example, | the other repositories which symbols should be looked for here. For example, | ||||
Phabricator lists "Arcanist" because it uses classes and functions defined | Phorge lists "Arcanist" because it uses classes and functions defined | ||||
in `arcanist/`. | in `arcanist/`. | ||||
== External Symbols == | == External Symbols == | ||||
By @{article@phabcontrib:Adding New Classes}, you can teach Phabricator | By @{article@contrib:Adding New Classes}, you can teach Phorge | ||||
about symbols from the outside world. | about symbols from the outside world. | ||||
Extend @{class:DiffusionExternalSymbolsSource}; Once loaded, your new | Extend @{class:DiffusionExternalSymbolsSource}; Once loaded, your new | ||||
implementation will be used any time a symbol is queried. | implementation will be used any time a symbol is queried. | ||||
See @{class:DiffusionPhpExternalSymbolsSource} and | See @{class:DiffusionPhpExternalSymbolsSource} and | ||||
@{class:DiffusionPythonExternalSymbolsSource} for example implementations. | @{class:DiffusionPythonExternalSymbolsSource} for example implementations. |
Content licensed under Creative Commons Attribution-ShareAlike 4.0 (CC-BY-SA) unless otherwise noted; code licensed under Apache 2.0 or other open source licenses. · CC BY-SA 4.0 · Apache 2.0