From fd8303aa7563dadd20c35a814f7c0a0e1dbe8666 Mon Sep 17 00:00:00 2001 From: epriestley Date: Wed, 21 Dec 2011 12:07:39 -0800 Subject: [PATCH] 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 --- .../generate_php_symbols.php | 2 +- .../import_project_symbols.php | 2 + src/docs/userguide/diffusion_symbols.diviner | 84 +++++++++++++++++++ 3 files changed, 87 insertions(+), 1 deletion(-) rename scripts/{crossref => symbols}/generate_php_symbols.php (98%) rename scripts/{crossref => symbols}/import_project_symbols.php (99%) create mode 100644 src/docs/userguide/diffusion_symbols.diviner diff --git a/scripts/crossref/generate_php_symbols.php b/scripts/symbols/generate_php_symbols.php similarity index 98% rename from scripts/crossref/generate_php_symbols.php rename to scripts/symbols/generate_php_symbols.php index 2a8de4738f..d648d0f010 100755 --- a/scripts/crossref/generate_php_symbols.php +++ b/scripts/symbols/generate_php_symbols.php @@ -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); diff --git a/scripts/crossref/import_project_symbols.php b/scripts/symbols/import_project_symbols.php similarity index 99% rename from scripts/crossref/import_project_symbols.php rename to scripts/symbols/import_project_symbols.php index fde7fb9ebd..84e5cea608 100755 --- a/scripts/crossref/import_project_symbols.php +++ b/scripts/symbols/import_project_symbols.php @@ -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"); diff --git a/src/docs/userguide/diffusion_symbols.diviner b/src/docs/userguide/diffusion_symbols.diviner new file mode 100644 index 0000000000..d17f95560d --- /dev/null +++ b/src/docs/userguide/diffusion_symbols.diviner @@ -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: + + + +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.