revi-archive/phorge-arcanist
1
0
Fork 0
mirror of https://we.phorge.it/source/arcanist.git synced 2024-11-22 06:42:41 +01:00
Code Issues Releases Wiki Activity

Reorganize documentation.

Browse source
This commit is contained in:
epriestley 2011-05-31 12:14:20 -07:00
parent d3816f1c9e
commit 03056c7206
4 changed files with 16 additions and 195 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

52
src/docs/arcconfig.diviner
View file

@ -1,52 +0,0 @@
@title Setting Up .arcconfig
@group config
Explains how to configure Arcanist projects with ##.arcconfig## files.
= .arcconfig Basics =
Arcanist uses ##.arcconfig## files to determine a number of things about project
configuration. For instance, these are things it figures out from
##.arcconfig##:
- where the logical root directory of a project is;
- which server Arcanist should send diffs to for code review; and
- which lint rules should be applied.
An ##.arcconfig## file is a JSON file which you check into your project's root.
A simple, valid file looks something like this:
{
"project_id" : "some_project_name",
"conduit_uri" : "https://phabricator.example.com/api/"
}
Here's what these options mean:
- **project_id**: a human-readable string identifying the project
- **conduit_uri**: the Conduit API URI for the Phabricator installation that
Arcanist should send diffs to for review. Generally, if you access
Phabricator at ##https://phabricator.example.com/##, the **conduit_uri** is
##https://phabricator.example.com/api/##. Be mindful about "http" vs
"https".
For an exhaustive list of available options, see below.
= Advanced .arcconfig =
Other options include:
- **lint_engine**: the name of a subclass of @{class:ArcanistLintEngine},
which should be used to apply lint rules to this project. See (TODO).
- **unit_engine**: the name of a subclass of
@{class:ArcanistBaseUnitTestEngine}, which should be used to apply unit
test rules to this project. See (TODO).
- **arcanist_configuration**: the name of a subclass of
@{class:ArcanistConfiguration} which can add new command flags for this
project or provide entirely new commands.
- **remote_hooks_installed**: tells Arcanist that you've set up remote hooks
in the master repository (see @{article:Installing Arcanist SVN Hooks} for
SVN, or (TODO) for git).
- **copyright_holder**: used by @{class:ArcanistLicenseLinter} to apply
license notices to source files.
- **phutil_libraries**: map of additional Phutil libraries to load at startup.

83
src/docs/building_new_configuration_classes.diviner
View file

@ -1,83 +0,0 @@
@title Building New Configuration Classes
@group config
Explains how to build new classes to control how Arcanist behaves.
= Overview =
Arcanist has some basic configuration options available in the ##.arcconfig##
file (see @{article:Setting Up .arcconfig}), but it can't handle everything. If
you want to customize Arcanist at a deeper level, you need to build new classes.
For instance:
- if you want to configure linters, or add new linters, you need to create a
new class which extends @{class:ArcanistLintEngine}.
- if you want to integrate with a unit testing framework, you need to create a
new class which extends @{class:ArcanistBaseUnitTestEngine}.
- if you you want to change how workflows behave, or add new workflows, you
need to create a new class which extends @{class:ArcanistConfiguration}.
Arcanist works through a sort of dependency-injection approach. For example,
Arcanist does not run lint rules by default, but you can set **lint_engine**
in your ##.arcconfig## to the name of a class which extends
@{class:ArcanistLintEngine}. When running from inside your project, Arcanist
will load this class and call methods on it in order to run lint. To make this
work, you need to do three things:
- actually write the class;
- add the library where the class exists to your ##.arcconfig##;
- add the class name to your ##.arcconfig## as the **lint_engine**,
**unit_engine**, or **arcanist_configuration**.
= Write the Class =
(TODO)
= Load the Class =
To make the class loadable, you need to put the path to it in your
##.arcconfig##, under **phutil_libraries**:
{
// ...
"phutil_libraries" : {
// ...
"my-library" : "/path/to/my/library",
// ...
}
// ...
}
You can either specify an absolute path, or a path relative to the project root.
When you run ##arc --trace##, you should see a message to the effect that it has
loaded your library.
For debugging or testing, you can also run Arcanist with the
##--load-phutil-library## flag:
arc --load-phutil-library=/path/to/library <command>
You can specify this flag more than once to load several libraries. Note that
if you use this flag, Arcanist will ignore any libraries listed in
##.arcconfig##.
= Use the Class =
This step is easy: just edit ##.arcconfig## to specify your class name as
the appropriate configuration value.
{
// ...
"lint_engine" : "MyCustomArcanistLintEngine",
// ...
}
Now, when you run Arcanist in your project, it will invoke your class when
appropriate.
For lint and unit tests, you can also use the ##--engine## flag override the
default engine:
arc lint --engine MyCustomArcanistLintEngine
This is mostly useful for debugging and testing.

39
src/docs/overview.diviner
View file

@ -3,29 +3,22 @@
Overview of Arcanist, a code workflow tool.
Arcanist (commonly, "arc") is the command-line frontend to Differential. A
detailed command reference is available by running ##arc help##.
Arcanist (commonly, "arc") is the command-line frontend to Phabricator and
Differential. A detailed command reference is available by running ##arc help##.
= Overview =
= Documentation =
Arcanist is the command-line interface to Differential, and supports some
related revision control operations. Arcanist allows you to do things like:
- send your code to Differential for review with ##arc diff##
- commit reviewed changes with ##arc commit## (svn) or ##arc amend## (git)
- check your code for syntax and style errors with ##arc lint##
- run unit tests that cover your changes with ##arc unit##
- export changes from Differential or the working copy with ##arc export##
- apply patches from Differential or patchfiles with ##arc patch##
- execute context-aware blame with ##arc cover##
- show Differential status with ##arc list##
In general, these workflows are agnostic to the underlying version control
system and will work properly in git or svn repositories.
= Configuring a New Project =
Create a .arcconfig file.
= SVN Basics =
The Arcanist documentation is primarily focused at Arcanist developers and
explains the project's internals. Arcanist user documentation which explains
how to use the tool is available in the Phabricator project:
- for an overview of Arcanist, see @{article@phabricator:Arcanist User
Guide}.
- for information on configuring a new project and setting up an
##.arcconfig## file, see @{article@phabricator:Arcanist User Guide:
Configuring a New Project}.
- to install remote hooks in a repository, see @{article@phabricator:Arcanist
User Guide: Repository Hooks}.
- to integrate Arcanist with linters, unit tests and custom workflows, see
@{article@phabricator:Arcanist User Guide: Customizing Lint, Unit Tests and
Workflows}.

37
src/docs/svn_hooks.diviner
View file

@ -1,37 +0,0 @@
@title Installing Arcanist SVN Hooks
@group config
Describes how to set up Arcanist as an SVN pre-commit hook.
= Installing Arcanist SVN Hooks =
You can install Arcanist as an SVN pre-commit hook, to reject commits which
contain lint errors. The immediate value of this is that syntax errors won't
be committable, but you can block other kinds of badness with appropriate lint
engines.
To install Arcanist as a pre-commit hook, add this to your svn/hooks/pre-commit:
#!/bin/sh
/usr/local/bin/php -f /path/to/arcanist/bin/arc svn-hook-pre-commit $@ 1>&2
Make sure you make this file executable, or you'll get an error for every commit
with an unhelpful error message. You also need to specify the full path to PHP
since SVN nukes ENV before executing scripts. Alternatively you can specify
PATH explicitly.
If your project is configured to run linters or lint engines which aren't part
of Arcanist, specify where to load them from with ##--load-phutil-library##:
--load-phutil-library=/path/to/library/root
Since SVN commit hooks run without access to a working copy, you'll need to keep
one checked out somewhere and reference it with ##--load-phutil-library## if you
build new linters or customize lint engines. For example, your hook might
look like this:
#!/bin/sh
/usr/local/bin/php -f /path/to/arcanist/bin/arc svn-hook-pre-commit \
--load-phutil-library=/path/to/custom/lint/engine \
--load-phutil-library=/path/to/custom/unittest/engine \
$@ 1>&2