src/docs/user/userguide/diffusion_symbols.diviner

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