[Summary view] [Print] [Text view]

   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    - link symbol uses in Differential code reviews to their definitions
  13    - allow you to search for symbols
  14    - let the IRC bot answer questions like "Where is SomeClass?"
  15  
  16  NOTE: Symbol indexing is somewhat new, and has broader support for PHP than for
  17  other languages.
  18  
  19  = Populating the Index =
  20  
  21  To populate the index, you need to write a script which identifies symbols in
  22  your codebase and set up a cronjob which pipes its output to:
  23  
  24    ./scripts/symbols/import_project_symbols.php
  25  
  26  Phabricator includes a script which can identify symbols in PHP projects:
  27  
  28    ./scripts/symbols/generate_php_symbols.php
  29  
  30  Phabricator also includes a script which can identify symbols in any
  31  programming language that has classes and/or functions, and is supported by
  32  Exuberant Ctags (http://ctags.sourceforge.net):
  33  
  34    ./scripts/symbols/generate_ctags_symbols.php
  35  
  36  If you want to identify symbols from another language, you need to write a
  37  script which can export them (for example, maybe by parsing a ##ctags## file).
  38  
  39  The output format of the script should be one symbol per line:
  40  
  41    <context> <name> <type> <lang> <line> <path>
  42  
  43  For example:
  44  
  45    ExampleClass exampleMethod function php 13 /src/classes/ExampleClass.php
  46  
  47  Context is, broadly speaking, the scope or namespace where the symbol is
  48  defined. For object-oriented languages, this is probably a class name. The
  49  symbols with that context are class constants, methods, properties, nested
  50  classes, etc. When printing symbols without a context (those that are defined
  51  globally, for instance), the ##<context>## field should be empty (that is, the
  52  line should start with a space).
  53  
  54  Your script should enumerate all the symbols in your project, and provide paths
  55  from the project root (where ".arcconfig" is) beginning with a "/".
  56  
  57  You can look at ##generate_php_symbols.php## for an example of how you might
  58  write such a script, and run this command to see its output:
  59  
  60    $ cd phabricator/
  61    $ find . -type f -name '*.php' | ./scripts/symbols/generate_php_symbols.php
  62  
  63  To actually build the symbol index, pipe this data to the
  64  `import_project_symbols.php` script, providing the project name:
  65  
  66    $ ./scripts/symbols/import_project_symbols.php yourproject < symbols_data
  67  
  68  Then just set up a cronjob to run that however often you like.
  69  
  70  You can test that the import worked by querying for symbols using the Conduit
  71  method ##differential.findsymbols##. Some features (like that method, and the
  72  IRC bot integration) will start working immediately. Others will require more
  73  configuration.
  74  
  75  = Configuring Differential Integration =
  76  
  77  To configure Differential integration, you need to tell Phabricator which
  78  projects have symbol indexes you want to use, and which other projects they
  79  should pull symbols from. To do this, go to
  80  {nav Repositories > Arcanist Projects > Edit} as an administrator. You need to
  81  fill out these fields:
  82  
  83    - **Repository**: Associate the project with a tracked repository.
  84    - **Indexed Languages**: Fill in all the languages you've built indexes for.
  85    - **Uses Symbols From**: If this project depends on other projects, add the
  86      other projects which symbols should be looked for here. For example,
  87      Phabricator lists "Arcanist" and "libphutil" because it uses classes and
  88      functions from these projects.
  89  
  90  Once you've configured a project, new revisions in that project will
  91  automatically link symbols in Differential.
  92  
  93  NOTE: Because this feature depends on the syntax highlighter, it will work
  94  better for some languages than others. It currently works fairly well for PHP,
  95  but your mileage may vary for other languages.