mirror of
https://we.phorge.it/source/phorge.git
synced 2024-11-21 22:32:41 +01:00
Document how to use the symbol importer
Summary: Some day we might have a fancy daemon for this, but for now at least provide some instructions on using the existing importers, etc., to index project symbols. Test Plan: - Generated documentation, read over the result. - Ran the example code. Reviewers: btrahan, jungejason, davidreuss Reviewed By: jungejason CC: aran, jungejason Maniphest Tasks: T315 Differential Revision: https://secure.phabricator.com/D1262
This commit is contained in:
parent
13155f8828
commit
fd8303aa75
3 changed files with 87 additions and 1 deletions
|
@ -23,7 +23,7 @@ require_once $root.'/scripts/__init_script__.php';
|
|||
phutil_require_module('phutil', 'console');
|
||||
phutil_require_module('phutil', 'parser/xhpast/bin');
|
||||
|
||||
if ($argc !== 1) {
|
||||
if ($argc !== 1 || posix_isatty(STDIN)) {
|
||||
echo phutil_console_format(
|
||||
"usage: find . -type f -name '*.php' | ./generate_php_symbols.php\n");
|
||||
exit(1);
|
|
@ -20,6 +20,8 @@
|
|||
$root = dirname(dirname(dirname(__FILE__)));
|
||||
require_once $root.'/scripts/__init_script__.php';
|
||||
|
||||
phutil_require_module('phutil', 'console');
|
||||
|
||||
if ($argc !== 2) {
|
||||
echo phutil_console_format(
|
||||
"usage: import_project_symbols.php __project_name__ < __symbol_file__\n");
|
84
src/docs/userguide/diffusion_symbols.diviner
Normal file
84
src/docs/userguide/diffusion_symbols.diviner
Normal file
|
@ -0,0 +1,84 @@
|
|||
@title Diffusion User Guide: Symbol Indexes
|
||||
@group userguide
|
||||
|
||||
Guide to configuring and using the symbol index.
|
||||
|
||||
= Overview =
|
||||
|
||||
Phabricator 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
|
||||
use the index to do things like:
|
||||
|
||||
- link symbol uses in Differential code reviews to their definitions
|
||||
- allow you to search for symbols
|
||||
- let the IRC bot answer questions like "Where is SomeClass?"
|
||||
|
||||
NOTE: Symbol indexing is somewhat new, and has broader support for PHP than for
|
||||
other languages.
|
||||
|
||||
= Populating the Index =
|
||||
|
||||
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:
|
||||
|
||||
./scripts/symbols/import_project_symbols.php
|
||||
|
||||
Phabricator includes a script which can identify symbols in PHP projects:
|
||||
|
||||
./scripts/symbols/generate_php_symbols.php
|
||||
|
||||
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).
|
||||
|
||||
The output format of the script should be one symbol per line:
|
||||
|
||||
<name> <type> <lang> <line> <path>
|
||||
|
||||
For example:
|
||||
|
||||
ExampleClass class php 13 /src/classes/ExampleClass.php
|
||||
|
||||
Your script should enumerate all the symbols in your project, and provide paths
|
||||
from the project root (where ".arcconfig" is) beginning with a "/". If there are
|
||||
any duplicate symbols, it should include logic to pick the "best" one -- symbol
|
||||
names must be unique within a project, type and language.
|
||||
|
||||
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:
|
||||
|
||||
$ cd phabricator/
|
||||
$ find . -type f -name '*.php' | ./scripts/symbols/generate_php_symbols.php
|
||||
|
||||
To actually build the symbol index, pipe this data to the
|
||||
##import_project_symbols.php## script, providing the project name:
|
||||
|
||||
$ ./scripts/symbols/import_project_symbols.php yourproject < symbols_data
|
||||
|
||||
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
|
||||
method ##differential.findsymbols##. Some features (like that method, and the
|
||||
IRC bot integration) will start working immediately. Others will require more
|
||||
configuration.
|
||||
|
||||
= Configuring Differential Integration =
|
||||
|
||||
To configure Differential integration, you need to tell Phabricator which
|
||||
projects have symbol indexes you want to use, and which other projects they
|
||||
should pull symbols from. To do this, go to
|
||||
##Repositories -> Arcanist Projects -> Edit## as an administrator. You need to
|
||||
fill out these fields:
|
||||
|
||||
- **Repository**: Associate the project with a tracked repository.
|
||||
- **Indexed Languages**: Fill in all the languages you've built indexes for.
|
||||
- **Uses Symbols From**: If this project depends on other projects, add the
|
||||
other projects which symbols should be looked for here. For example,
|
||||
Phabricator lists "Arcanist" and "libphutil" because it uses classes and
|
||||
functions from these projects.
|
||||
|
||||
Once you've configured a project, new revisions in that project will
|
||||
automatically link symbols in Differential.
|
||||
|
||||
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,
|
||||
but your milage may vary for other languages.
|
Loading…
Reference in a new issue