No OneTemporary
Actions

Size

19 KB

Referenced Files

None

Subscribers

None

View Options

	diff --git a/src/docs/user/userguide/arcanist_new_project.diviner b/src/docs/user/userguide/arcanist_new_project.diviner
	index fbb2ad4a45..448d3ea947 100644
	--- a/src/docs/user/userguide/arcanist_new_project.diviner
	+++ b/src/docs/user/userguide/arcanist_new_project.diviner
	@@ -1,227 +1,223 @@
	@title Arcanist User Guide: Configuring a New Project
	@group userguide

	Explains how to configure Arcanist projects with `.arcconfig` files.

	= Overview =

	In most cases, you should be able to use `arc` without specifically configuring
	your project for it. If you want to adjust `arc` behaviors, you can create a
	`.arcconfig` file in your project to provide project-specific settings.

	= .arcconfig Basics =

	An `.arcconfig` file is a JSON file which you check into your project's root.

	Arcanist uses `.arcconfig` files to customize a number of things about its
	behavior. The first thing you're likely to want to configure is the URI
	for your Phabricator install. A simple, valid file looks something like this:

	name=.arcconfig
	{
	"phabricator.uri" : "https://phabricator.example.com/"
	}

	For details on available options, see below.

	NOTE: You should commit your `.arcconfig` file! It contains project
	configuration, not user configuration.

	= Advanced .arcconfig =

	Common options are:

	- phabricator.uri: the URI for the Phabricator install that `arc` should
	connect to when run in this project. This option was previously called
	`conduit_uri`.
	- repository.callsign: The callsign of this repository in Diffusion.
	Normally, `arc` can detect this automatically, but if it can't figure it out
	you can specify it explicitly. Use `arc which` to understand the detection
	process.
	- history.immutable: Configures `arc` to use workflows which never rewrite
	history in the working copy. By default, `arc` will perform some rewriting
	of unpublished history (amending commit messages, squash merging) on some
	workflows in Git. The distinctions are covered in detail below.

	Other options include:

	- load: list of additional Phutil libraries to load at startup.
	See below for details about path resolution, or see
	@{article:libphutil Libraries User Guide} for a general introduction to
	libphutil libraries.
	- - project.name: name an "Arcanist Project" to associate this working
	- copy (Git, Mercurial) or directory (SVN) with. Previously, this was a
	- required option, but `arc` can now usually operate without it in Git and
	- Mercurial. This option was previously called `project_id`.
	- https.cabundle: specifies the path to an alternate certificate bundle
	for use when making HTTPS connections.
	- 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: Lint}.
	- unit.engine: the name of a subclass of
	@{class@arcanist:ArcanistUnitTestEngine}, which should be used to apply
	unit test rules to this project. See
	@{article:Arcanist User Guide: Customizing Lint, Unit Tests and Workflows}.

	These options are supported, but their use is discouraged:

	- http.basicauth.user: specify an HTTP basic auth username for use when
	connecting to Phabricator.
	- http.basicauth.pass: specify an HTTP basic auth password for use when
	connecting to Phabricator.
	- https.blindly-trust-domains: a list of domains to trust blindly over
	HTTPS, even if their certificates are invalid. This is a brute force
	solution to certificate validity problems, and is discouraged. Instead,
	use valid certificates.

	For a complete list of options, run `arc get-config`. Although all
	options can be set in `.arcconfig`, some options (like `editor`) usually do not
	make sense to set here because they're likely to vary from user to user.

	= History Mutability =

	Arcanist workflows run in two broad modes: either history is //mutable// or
	//immutable//. Under a //mutable// history, `arc` commands may rewrite the
	working copy history; under an //immutable// history, they may not.

	You control history mutability by setting `history.immutable` to `true` or
	`false` in your configuration. By default, it is `false` in Git (i.e.,
	//mutable//) and `true` in Mercurial (i.e., //immutable//). The sections below
	explain how these settings affect workflows.

	== History Mutability: Git ==

	In a workflow with //mutable// history, you rewrite local history. You develop
	in feature branches, but squash or amend before pushing by using ##git commit
	--amend##, ##git rebase -i##, or `git merge --squash`. Generally, one idea in
	the remote is represented by one commit.

	In a workflow with //immutable// history, you do not rewrite local history. You
	develop in feature branches and push them without squashing commits. You do not
	use ##git commit --amend## or ##git rebase -i##. Generally, one idea in the
	remote is represented by many commits.

	Practically, these are the differences you'll see based on your setting:

	- Mutable
	- `arc diff` will prompt you to amend lint changes into HEAD.
	- `arc diff` will amend the commit message in HEAD after creating a
	revision.
	- `arc land` will default to the `--squash` strategy.
	- `arc amend` will amend the commit message in HEAD with information from
	the corresponding or specified Differential revision.
	- Immutable
	- `arc diff` will abort if it makes lint changes.
	- `arc diff` will not amend the commit message in HEAD after creating a
	revision.
	- `arc land` will default to the `--merge` strategy.
	- `arc amend` will exit with an error message.

	== History Mutability: Mercurial ==

	Before version 2.2, stock Mercurial has no history mutation commands, so
	this setting has no effect. With Mercurial 2.2. or newer, making history
	//mutable// means:

	- Mutable (versions 2.2 and newer)
	- `arc diff` will amend the commit message in `.` after creating a
	revision.
	- `arc amend` will amend the commit message in `.` with information from
	the corresponding or specified Differential revision.
	- Immutable (or versions prior to 2.2)
	- `arc diff` will not amend the commit message in `.` after creating a
	revision.
	- `arc amend` will exit with an error message.

	= How Libraries Are Located =

	If you specify an external library to load, like 'examplelib', and use a
	relative path like this:

	{
	...
	"load": [
	"examplelib/src"
	],
	...
	}

	...arc looks for it by trying these paths:

	- `path/to/root/examplelib/src/` First, arc looks in the project's root
	directory (where the `.arcconfig` lives) to see if the library is part of
	the project. This makes it easy to just put project-specific code in a
	project.
	- `path/to/root/../examplelib/src/` Next, arc looks //next to// the project's
	root directory to see if the library is in a sibling directory. If you
	work with several repositories, this makes it easy to put all the `arc`
	code in one repository and just check it out in the same directory as
	everything else.
	- `php/include/path/examplelib/src` Finally, arc falls back to PHP, which
	will look in paths described in the `include_path` php.ini setting. This
	allows you to install libraries in some global location if you prefer.

	You can alternately supply an absolute path, like `/var/arc/examplelib/src`, but
	then everyone will need to install the library at that exact location.

	NOTE: Specify the path to the directory which includes
	`__phutil_library_init__.php`. For example, if your init file is in
	`examplelib/src/__phutil_library_init__.php`, specify `examplelib/src`,
	not just `examplelib/`.

	The general intent here is:

	- Put project-specific code in some directory in the project, like
	`support/arc/src/`.
	- Put shared code (e.g., which enforces general coding standards or hooks
	up to unit tests or whatever) in a separate repository and check it out
	next to other repositories.
	- Or put everything in some standard location and add it to `include_path`.

	= Running Without .arcconfig =

	Although you don't need to set up `.arcconfig`, and you can run `arc` command
	that require a working copy in any Git, Subversion or Mercurial working copy,
	some features won't work unless you set up an `.arcconfig` file.

	Without `.arcconfig`:

	- You will need to set a default Phabricator URI with
	`arc set-config default <uri>`, or specify an explicit URI
	with `--conduit-uri` each time you run a command.
	- You will not be able to run linters through arc unless you pass `--engine`
	explicitly.
	- You will not be able to customize certain linter parameters even with
	`--engine`.
	- You will not be able to run unit tests through arc unless you pass
	`--engine` explicitly.
	- You will not be able to trigger lint and unit integration through
	`arc diff`.
	- You will not be able to put Git working copies into immutable history mode
	(see below).
	- You will not be able to specify a repository encoding. UTF-8 will be assumed
	if you do not pass `--encoding`.
	- You will not be able to add plugins to arc to modify existing workflows or
	add new ones.
	- You will not be able to load additional libraries unless you specify them
	explicitly with `--load-phutil-library`.
	- Symbol index integration, which allows users to click function or class
	names in Differential and jump to their definitions, will not work.
	- `arc patch` will be unable to detect that you are applying changes to the
	wrong project.
	- In Subversion, `arc` will be unable to determine the canonical root
	of a project, and will assume it is the working directory (in Subversion
	prior to 1.7) or the root of the checkout (in Subversion after 1.7). This
	means the paths of files in diffs won't be anchored to the same place,
	and will have different amounts of path context, which may be confusing for
	reviewers and will sometimes prevent patches from applying properly if they
	are applied against a different directory than they were generated from.
	- In Subversion, `arc` will be unable to guess that you intend to update
	an existing revision; you must use `--update` explicitly or `--preview`
	and attach diffs via the web interface.

	= Next Steps =

	Continue by:

	- returning to @{article:Arcanist User Guide}.
	diff --git a/src/docs/user/userguide/arcanist_quick_start.diviner b/src/docs/user/userguide/arcanist_quick_start.diviner
	index 261056bbeb..98633bfaef 100644
	--- a/src/docs/user/userguide/arcanist_quick_start.diviner
	+++ b/src/docs/user/userguide/arcanist_quick_start.diviner
	@@ -1,86 +1,83 @@
	@title Arcanist Quick Start
	@group userguide

	Quick guide to getting Arcanist working for a new project.

	This is a summary of steps to install Arcanist, configure a project for use with
	it, and run `arc` to send changes for review.

	= Install Arcanist =

	For detailed instructions on installing Arcanist, see
	@{article:Arcanist User Guide}.

	- For Mac OS X, see @{article:Arcanist User Guide: Mac OS X}.
	- For Windows, see @{article:Arcanist User Guide: Windows}.

	First, install dependencies:

	- Install PHP.
	- Install Git.

	Then install Arcanist itself:

	$ mkdir somewhere/
	$ cd somewhere/
	somewhere/ $ git clone https://github.com/phacility/libphutil.git
	somewhere/ $ git clone https://github.com/phacility/arcanist.git

	Add `arc` to your path:

	$ export PATH="$PATH:/somewhere/arcanist/bin/"

	This won't work for Windows, see @{article:Arcanist User Guide: Windows} for
	instructions.

	= Configure Your Project =

	For detailed instructions on project configuration, see
	@{article:Arcanist User Guide: Configuring a New Project}.

	Create a `.arcconfig` file in your project's working copy:

	$ cd yourproject/
	yourproject/ $ $EDITOR .arcconfig
	yourproject/ $ cat .arcconfig
	{
	- "project.name" : "yourprojectname",
	"phabricator.uri" : "https://phabricator.example.com/"
	}

	-Set `project.name` to a string that identifies the project.
	-
	Set `phabricator.uri` to the URI for your Phabricator install (where `arc`
	should send changes to).

	NOTE: You should commit this file to the repository.

	= Install Arcanist Credentials =

	Credentials allow you to authenticate. You must have an account on Phabricator
	before you can perform this step.

	$ cd yourproject/
	yourproject/ $ arc install-certificate
	...

	Follow the instructions. This will link your user account on your local machine
	to your Phabricator account.

	= Send Changes For Review =

	For detailed instructions on using `arc diff`, see
	@{article:Arcanist User Guide: arc diff}.

	$ $EDITOR file.c
	$ arc diff

	= Next Steps =

	Continue by:

	- learning more about project configuration with
	@{article:Arcanist User Guide: Configuring a New Project}; or
	- learning more about `arc diff` with
	@{article:Arcanist User Guide: arc diff}; or
	- returning to @{article:Arcanist User Guide}.
	diff --git a/src/docs/user/userguide/libraries.diviner b/src/docs/user/userguide/libraries.diviner
	index 33f6f57b67..656b167d8d 100644
	--- a/src/docs/user/userguide/libraries.diviner
	+++ b/src/docs/user/userguide/libraries.diviner
	@@ -1,156 +1,155 @@
	@title libphutil Libraries User Guide
	@group userguide

	Guide to creating and managing libphutil libraries.

	= Overview =

	libphutil includes a library system which organizes PHP classes and functions
	into modules. Some extensions and customizations of Arcanist and Phabricator
	require you to make code available to Phabricator by providing it in a libphutil
	library.

	For example, if you want to store files in some kind of custom storage engine,
	you need to write a class which can interact with that engine and then tell
	Phabricator to load it.

	In general, you perform these one-time setup steps:

	- Create a new directory.
	- Use ##arc liberate## to initialize and name the library.
	- Add a dependency on Phabricator if necessary.
	- Add the library to your Phabricator config or ##.arcconfig## so it will be
	loaded at runtime.

	Then, to add new code, you do this:

	- Write or update classes.
	- Update the library metadata by running ##arc liberate## again.

	= Creating a New Library =

	To create a new libphutil library:

	$ mkdir libcustom/
	$ cd libcustom/
	libcustom/ $ arc liberate src/

	Now you'll get a prompt like this:

	lang=txt
	No library currently exists at that path...
	The directory '/some/path/libcustom/src' does not exist.

	Do you want to create it? [y/N] y
	Creating new libphutil library in '/some/path/libcustom/src'.
	Choose a name for the new library.

	What do you want to name this library?

	Choose a library name (in this case, "libcustom" would be appropriate) and it
	you should get some details about the library initialization:

	lang=txt
	Writing '__phutil_library_init__.php' to
	'/some/path/libcustom/src/__phutil_library_init__.php'...
	Using library root at 'src'...
	Mapping library...
	Verifying library...
	Finalizing library map...
	OKAY Library updated.

	This will write three files:

	- ##src/.phutil_module_cache## This is a cache which makes "arc liberate"
	faster when you run it to update the library. You can safely remove it at
	any time. If you check your library into version control, you can add this
	file to ignore rules (like .gitignore).
	- ##src/__phutil_library_init__.php## This records the name of the library and
	tells libphutil that a library exists here.
	- ##src/__phutil_library_map__.php## This is a map of all the symbols
	(functions and classes) in the library, which allows them to be autoloaded
	at runtime and dependencies to be statically managed by "arc liberate".

	= Linking with Phabricator =

	If you aren't using this library with Phabricator (e.g., you are only using it
	with Arcanist or are building something else on libphutil) you can skip this
	step.

	But, if you intend to use this library with Phabricator, you need to define its
	dependency on Phabricator by creating a ##.arcconfig## file which points at
	Phabricator. For example, you might write this file to
	`libcustom/.arcconfig`:

	{
	- "project.name" : "libcustom",
	- "load" : [
	+ "load": [
	"phabricator/src/"
	]
	}

	For details on creating a ##.arcconfig##, see
	@{article:Arcanist User Guide: Configuring a New Project}. In general, this
	tells ##arc liberate## that it should look for symbols in Phabricator when
	performing static analysis.

	NOTE: If Phabricator isn't located next to your custom library, specify a
	path which actually points to the ##phabricator/## directory.

	You do not need to declare dependencies on ##arcanist## or ##libphutil##,
	since ##arc liberate## automatically loads them.

	Finally, edit your Phabricator config to tell it to load your library at
	runtime, by adding it to ##load-libraries##:

	...
	'load-libraries' => array(
	'libcustom' => 'libcustom/src/',
	),
	...

	Now, Phabricator will be able to load classes from your custom library.

	= Writing Classes =

	To actually write classes, create a new module and put code in it:

	libcustom/ $ mkdir src/example/
	libcustom/ $ nano src/example/ExampleClass.php # Edit some code.

	Now, run ##arc liberate## to regenerate the static resource map:

	libcustom/ $ arc liberate src/

	This will automatically regenerate the static map of the library.

	= What You Can Extend And Invoke =

	libphutil, Arcanist and Phabricator are strict about extensibility of classes
	and visibility of methods and properties. Most classes are marked ##final##, and
	methods have the minimum required visibility (protected or private). The goal of
	this strictness is to make it clear what you can safely extend, access, and
	invoke, so your code will keep working as the upstream changes.

	When developing libraries to work with libphutil, Arcanist and Phabricator, you
	should respect method and property visibility and extend only classes marked
	`@stable`. They are rendered with a large callout in the documentation (for
	example: @{class@libphutil:AbstractDirectedGraph}). These classes are external
	interfaces intended for extension.

	If you want to extend a class but it is not marked ##@stable##, here are some
	approaches you can take:

	- Good: If possible, use composition rather than extension to build your
	feature.
	- Good: Check the documentation for a better way to accomplish what you're
	trying to do.
	- Good: Let us know what your use case is so we can make the class tree more
	flexible or configurable, or point you at the right way to do whatever
	you're trying to do, or explain why we don't let you do it.
	- Discouraged: Send us a patch removing "final" (or turning "protected" or
	"private" into "public"). We generally will not accept these patches, unless
	there's a good reason that the current behavior is wrong.
	- Discouraged: Create an ad-hoc local fork and remove "final" in your copy of
	the code. This will make it more difficult for you to upgrade in the future.
	- Discouraged: Use Reflection to violate visibility keywords.

File Metadata

Mime Type: text/x-diff
Expires: Tue, Dec 2, 12:13 AM (1 d, 1 h)
Storage Engine: blob
Storage Format: Raw Data
Storage Handle: 431391
Default Alt Text: (19 KB)

No OneTemporaryActions

View Options

File Metadata

Event Timeline

No OneTemporary
Actions