No OneTemporary
Actions

Size

9 KB

Referenced Files

None

Subscribers

None

View Options

	diff --git a/.divinerconfig b/.divinerconfig
	index 9d8afb0a1b..e20237a757 100644
	--- a/.divinerconfig
	+++ b/.divinerconfig
	@@ -1,27 +1,27 @@
	{
	"name" : "Phabricator",
	- "src_base" : "https://github.com/facebook/phabricator/blob/master",
	+ "src_base" : "https://secure.phabricator.com/diffusion/P/browse/origin:master",
	"groups" : {
	"intro" : "Introduction",
	"config" : "Configuration",
	"userguide" : "Application User Guides",
	"contrib" : "Contributing",
	"flavortext" : "Flavor Text",
	"developer" : "Phabricator Developer Guides",
	"differential" : "Differential (Code Review)",
	"diffusion" : "Diffusion (Repository Browser)",
	"maniphest" : "Maniphest (Task Tracking)",
	"herald" : "Herald (Notifications)",
	"celerity" : "Celerity (CSS/JS Management)",
	"aphront" : "Aphront (Web Stack)",
	"console" : "DarkConsole (Debugging Console)",
	"storage" : "Storage",
	"irc" : "IRC",
	"markup" : "Remarkup Extensions"
	},
	"engines" : [
	["DivinerArticleEngine", {}],
	["DivinerXHPEngine", {}]
	]
	}

	diff --git a/src/docs/userguide/arcanist_lint_unit.diviner b/src/docs/userguide/arcanist_lint_unit.diviner
	index 4fbb8655ab..bb7648d661 100644
	--- a/src/docs/userguide/arcanist_lint_unit.diviner
	+++ b/src/docs/userguide/arcanist_lint_unit.diviner
	@@ -1,85 +1,109 @@
	@title Arcanist User Guide: Customizing Lint, Unit Tests and Workflows
	@group userguide

	Explains how to build new classes to control how Arcanist behaves.

	-NOTE: TODO: This document is pretty trash, follow at your own risk.
	-
	= 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:
	+file (see @{article:Arcanist User Guide: Configuring a New Project}), 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}.
	+ new class which extends @{class@arcanist:ArcanistLintEngine}.
	- if you want to integrate with a unit testing framework, you need to create a
	- new class which extends @{class:ArcanistBaseUnitTestEngine}.
	+ new class which extends @{class@arcanist: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}.
	+ need to create a new class which extends
	+ @{class@arcanist: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:
	+@{class@arcanist: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)
	+Start by creating a new phutil library -- this is a directory which will contain
	+class files for Arcanist to load. You can either put it inside your project, or
	+outside (if you want to share lint rules between several projects, for
	+instance). To create a new library, run ##arc liberate##:
	+
	+ $ arc liberate path/to/new/library
	+
	+This will prompt you to name your library and create a new directory on disk.
	+Create a new ##lint/## directory in this library (or ##unit/##, or whatever you
	+want). This creates a module. Put ##CustomArcanistLintEngine.php## inside the
	+##lint/## directory:
	+
	+ lang=php
	+ <?php
	+
	+ class CustomArcanistLintEngine extends ArcanistLintEngine {
	+
	+ }
	+
	+Now run ##arc liberate## on the library again. Whenever you add, remove, or
	+rename modules or classes you should run ##arc liberate## to update the
	+classmap.
	+
	+You can either write the class body now (refer to the documentation for the
	+class you are extending) or continue with integrating it into your project.

	= 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",
	+ "library-a" : "/path/to/my/library", // Absolute path
	+ "library-b" : "support/arcanist", // Relative path in this project
	// ...
	}
	// ...
	}

	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.
	+When you run ##arc list --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",
	+ "lint_engine" : "CustomArcanistLintEngine",
	// ...
	}

	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.
	diff --git a/src/docs/userguide/arcanist_new_project.diviner b/src/docs/userguide/arcanist_new_project.diviner
	index 8aab8d4cb3..43a1b53c33 100644
	--- a/src/docs/userguide/arcanist_new_project.diviner
	+++ b/src/docs/userguide/arcanist_new_project.diviner
	@@ -1,52 +1,52 @@
	@title Arcanist User Guide: Configuring a New Project
	@group userguide

	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/"
	+ "conduit_uri" : "https://phabricator.example.com/"
	}

	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".
	+ - conduit_uri: the URI for the Phabricator installation that Arcanist
	+ should send diffs to for review. 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).
	+ - lint_engine: the name of a subclass of
	+ @{class@arcanist:ArcanistLintEngine}, which should be used to apply lint
	+ rules to this project. See @{article:Arcanist User Guide: Customizing Lint,
	+ Unit Tests and Workflows}.
	- unit_engine: the name of a subclass of
	- @{class:ArcanistBaseUnitTestEngine}, which should be used to apply unit
	- test rules to this project. See (TODO).
	+ @{class@arcanist:ArcanistBaseUnitTestEngine}, which should be used to apply
	+ unit test rules to this project. See
	+ @{article:Arcanist User Guide: Customizing Lint, Unit Tests and Workflows}.
	- arcanist_configuration: the name of a subclass of
	- @{class:ArcanistConfiguration} which can add new command flags for this
	- project or provide entirely new commands.
	+ @{class@arcanist: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.
	+ in the master repository (see @{article:Arcanist User Guide: Repository
	+ Hooks}).
	+ - copyright_holder: used by @{class@arcanist:ArcanistLicenseLinter} to
	+ apply license notices to source files.
	- phutil_libraries: map of additional Phutil libraries to load at startup.

File Metadata

Mime Type: text/x-diff
Expires: Tue, Dec 2, 7:10 AM (12 h, 45 m)
Storage Engine: blob
Storage Format: Raw Data
Storage Handle: 431703
Default Alt Text: (9 KB)

No OneTemporaryActions

View Options

File Metadata

Event Timeline

No OneTemporary
Actions