mirror of
https://we.phorge.it/source/phorge.git
synced 2024-11-28 01:32:42 +01:00
Remove or correct various "phabricator/" references to "libphutil"
Summary: Ref T13395. "libphutil/" was stripped for parts, but some documentation still references it. This is mostly minor corrections, but: - Removes "Javelin at Facebook", long obsolete. - Removes "php FPM warmup", which was always a prototype and is obsoleted by PHP preloading in recent PHP. Test Plan: `grep` / reading Maniphest Tasks: T13395 Differential Revision: https://secure.phabricator.com/D21624
This commit is contained in:
parent
30d58de1bc
commit
42c0c0e3d2
31 changed files with 83 additions and 261 deletions
|
@ -1,38 +0,0 @@
|
||||||
<?php
|
|
||||||
|
|
||||||
/**
|
|
||||||
* NOTE: This is an ADVANCED feature that improves performance but adds a lot
|
|
||||||
* of complexity! This is only suitable for production servers because workers
|
|
||||||
* won't pick up changes between when they spawn and when they handle a request.
|
|
||||||
*
|
|
||||||
* Phabricator spends a significant portion of its runtime loading classes
|
|
||||||
* and functions, even with APC enabled. Since we have very rigidly-defined
|
|
||||||
* rules about what can go in a module (specifically: no side effects), it
|
|
||||||
* is safe to load all the libraries *before* we receive a request.
|
|
||||||
*
|
|
||||||
* Normally, SAPIs don't provide a way to do this, but with a patched PHP-FPM
|
|
||||||
* SAPI you can provide a warmup file that it will execute before a request
|
|
||||||
* is received.
|
|
||||||
*
|
|
||||||
* We're limited in what we can do here, since request information won't
|
|
||||||
* exist yet, but we can load class and function definitions, which is what
|
|
||||||
* we're really interested in.
|
|
||||||
*
|
|
||||||
* Once this file exists, the FCGI process will drop into its normal accept loop
|
|
||||||
* and eventually process a request.
|
|
||||||
*/
|
|
||||||
function __warmup__() {
|
|
||||||
$root = dirname(dirname(dirname(dirname(__FILE__))));
|
|
||||||
require_once $root.'/libphutil/src/__phutil_library_init__.php';
|
|
||||||
require_once $root.'/arcanist/src/__phutil_library_init__.php';
|
|
||||||
require_once $root.'/phabricator/src/__phutil_library_init__.php';
|
|
||||||
|
|
||||||
// Load every symbol. We could possibly refine this -- we don't need to load
|
|
||||||
// every Controller, for instance.
|
|
||||||
$loader = new PhutilSymbolLoader();
|
|
||||||
$loader->selectAndLoadSymbols();
|
|
||||||
|
|
||||||
define('__WARMUP__', true);
|
|
||||||
}
|
|
||||||
|
|
||||||
__warmup__();
|
|
|
@ -9,15 +9,12 @@ set -x
|
||||||
# to work without modifications.
|
# to work without modifications.
|
||||||
|
|
||||||
# NOTE: This script assumes you are running it from a directory which contains
|
# NOTE: This script assumes you are running it from a directory which contains
|
||||||
# arcanist/, libphutil/, and phabricator/.
|
# arcanist/ and phabricator/.
|
||||||
|
|
||||||
ROOT=`pwd` # You can hard-code the path here instead.
|
ROOT=`pwd` # You can hard-code the path here instead.
|
||||||
|
|
||||||
### UPDATE WORKING COPIES ######################################################
|
### UPDATE WORKING COPIES ######################################################
|
||||||
|
|
||||||
cd $ROOT/libphutil
|
|
||||||
git pull
|
|
||||||
|
|
||||||
cd $ROOT/arcanist
|
cd $ROOT/arcanist
|
||||||
git pull
|
git pull
|
||||||
|
|
||||||
|
|
|
@ -156,7 +156,7 @@ abstract class PhabricatorConduitController extends PhabricatorController {
|
||||||
|
|
||||||
$parts = array();
|
$parts = array();
|
||||||
|
|
||||||
$libphutil_path = 'path/to/libphutil/src/__phutil_library_init__.php';
|
$libphutil_path = 'path/to/arcanist/support/init/init-script.php';
|
||||||
|
|
||||||
$parts[] = '<?php';
|
$parts[] = '<?php';
|
||||||
$parts[] = "\n\n";
|
$parts[] = "\n\n";
|
||||||
|
|
|
@ -1151,7 +1151,7 @@ final class PhabricatorRepository extends PhabricatorRepositoryDAO
|
||||||
/**
|
/**
|
||||||
* Get a parsed object representation of the repository's remote URI..
|
* Get a parsed object representation of the repository's remote URI..
|
||||||
*
|
*
|
||||||
* @return wild A @{class@libphutil:PhutilURI}.
|
* @return wild A @{class@arcanist:PhutilURI}.
|
||||||
* @task uri
|
* @task uri
|
||||||
*/
|
*/
|
||||||
public function getRemoteURIObject() {
|
public function getRemoteURIObject() {
|
||||||
|
|
|
@ -21,7 +21,7 @@ available by looking at all of the subclasses of
|
||||||
@{class@phabricator:PhabricatorApplication}. It
|
@{class@phabricator:PhabricatorApplication}. It
|
||||||
discovers available workflows in `arc` by looking at all of the subclasses of
|
discovers available workflows in `arc` by looking at all of the subclasses of
|
||||||
@{class@arcanist:ArcanistWorkflow}. It discovers available locales
|
@{class@arcanist:ArcanistWorkflow}. It discovers available locales
|
||||||
by looking at all of the subclasses of @{class@libphutil:PhutilLocale}.
|
by looking at all of the subclasses of @{class@arcanist:PhutilLocale}.
|
||||||
|
|
||||||
This pattern holds in many cases, so you can often add functionality by adding
|
This pattern holds in many cases, so you can often add functionality by adding
|
||||||
new classes with no other work. Phabricator will automatically discover and
|
new classes with no other work. Phabricator will automatically discover and
|
||||||
|
@ -49,8 +49,8 @@ This is intended as a quick way to add small pieces of functionality, test new
|
||||||
features, or get started on a larger project. Extending Phabricator like this
|
features, or get started on a larger project. Extending Phabricator like this
|
||||||
imposes a small performance penalty compared to using a library.
|
imposes a small performance penalty compared to using a library.
|
||||||
|
|
||||||
This directory exists in all libphutil libraries, so you can find similar
|
This directory exists in all libphutil libraries, so you can find a similar
|
||||||
directories in `arcanist/src/extensions/` and `libphutil/src/extensions/`.
|
directory in `arcanist/src/extensions/`.
|
||||||
|
|
||||||
For example, to add a new application, create a file like this one and add it
|
For example, to add a new application, create a file like this one and add it
|
||||||
to `phabricator/src/extensions/`.
|
to `phabricator/src/extensions/`.
|
||||||
|
@ -171,8 +171,8 @@ performing static analysis.
|
||||||
NOTE: If Phabricator isn't located next to your custom library, specify a
|
NOTE: If Phabricator isn't located next to your custom library, specify a
|
||||||
path which actually points to the `phabricator/` directory.
|
path which actually points to the `phabricator/` directory.
|
||||||
|
|
||||||
You do not need to declare dependencies on `arcanist` or `libphutil`,
|
You do not need to declare dependencies on `arcanist`, since `arc liberate`
|
||||||
since `arc liberate` automatically loads them.
|
automatically loads them.
|
||||||
|
|
||||||
Finally, edit your Phabricator config to tell it to load your library at
|
Finally, edit your Phabricator config to tell it to load your library at
|
||||||
runtime, by adding it to `load-libraries`:
|
runtime, by adding it to `load-libraries`:
|
||||||
|
@ -206,8 +206,8 @@ This will automatically regenerate the static map of the library.
|
||||||
What You Can Extend And Invoke
|
What You Can Extend And Invoke
|
||||||
==============================
|
==============================
|
||||||
|
|
||||||
libphutil, Arcanist and Phabricator are strict about extensibility of classes
|
Arcanist and Phabricator are strict about extensibility of classes and
|
||||||
and visibility of methods and properties. Most classes are marked `final`, and
|
visibility of methods and properties. Most classes are marked `final`, and
|
||||||
methods have the minimum required visibility (protected or private). The goal
|
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
|
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.
|
invoke, so your code will keep working as the upstream changes.
|
||||||
|
@ -215,8 +215,8 @@ invoke, so your code will keep working as the upstream changes.
|
||||||
IMPORTANT: We'll still break APIs frequently. The upstream does not support
|
IMPORTANT: We'll still break APIs frequently. The upstream does not support
|
||||||
extension development, and none of these APIs are stable.
|
extension development, and none of these APIs are stable.
|
||||||
|
|
||||||
When developing libraries to work with libphutil, Arcanist and Phabricator, you
|
When developing libraries to work with Arcanist and Phabricator, you should
|
||||||
should respect method and property visibility.
|
respect method and property visibility.
|
||||||
|
|
||||||
If you want to add features but can't figure out how to do it without changing
|
If you want to add features but can't figure out how to do it without changing
|
||||||
Phabricator code, here are some approaches you may be able to take:
|
Phabricator code, here are some approaches you may be able to take:
|
||||||
|
|
|
@ -47,10 +47,9 @@ Before you file a report, here are some common solutions to problems:
|
||||||
issues to be fixed in less than 24 hours, so even if you've updated recently
|
issues to be fixed in less than 24 hours, so even if you've updated recently
|
||||||
you should update again. If you aren't sure how to update, see the next
|
you should update again. If you aren't sure how to update, see the next
|
||||||
section.
|
section.
|
||||||
- **Update Libraries**: Make sure `libphutil/`, `arcanist/` and
|
- **Update Libraries**: Make sure `arcanist/` and `phabricator/` are all up
|
||||||
`phabricator/` are all up to date. Users often update `phabricator/` but
|
to date. Users often update `phabricator/` but forget to update `arcanist/`.
|
||||||
forget to update `arcanist/` or `libphutil/`. When you update, make sure you
|
When you update, make sure you update all three libraries.
|
||||||
update all three libraries.
|
|
||||||
- **Restart Apache or PHP-FPM**: Phabricator uses caches which don't get
|
- **Restart Apache or PHP-FPM**: Phabricator uses caches which don't get
|
||||||
reset until you restart Apache or PHP-FPM. After updating, make sure you
|
reset until you restart Apache or PHP-FPM. After updating, make sure you
|
||||||
restart.
|
restart.
|
||||||
|
|
|
@ -1,7 +1,7 @@
|
||||||
@title Contributor Introduction
|
@title Contributor Introduction
|
||||||
@group contrib
|
@group contrib
|
||||||
|
|
||||||
Introduction to contributing to Phabricator, Arcanist and libphutil.
|
Introduction to contributing to Phabricator and Arcanist.
|
||||||
|
|
||||||
Overview
|
Overview
|
||||||
========
|
========
|
||||||
|
|
|
@ -212,9 +212,9 @@ outside of our comfort zone.
|
||||||
Writing and Submitting Patches
|
Writing and Submitting Patches
|
||||||
==================
|
==================
|
||||||
|
|
||||||
To actually submit a patch, run `arc diff` in `phabricator/`, `arcanist/`, or
|
To actually submit a patch, run `arc diff` in `phabricator/` or `arcanist/`.
|
||||||
`libphutil/`. When executed in these directories, `arc` should automatically
|
When executed in these directories, `arc` should automatically talk to the
|
||||||
talk to the upstream install. You can add `epriestley` as a reviewer.
|
upstream install. You can add `epriestley` as a reviewer.
|
||||||
|
|
||||||
You should read the relevant coding convention documents before you submit a
|
You should read the relevant coding convention documents before you submit a
|
||||||
change. If you're a new contributor, you don't need to worry about this too
|
change. If you're a new contributor, you don't need to worry about this too
|
||||||
|
|
|
@ -2,7 +2,7 @@
|
||||||
@group standards
|
@group standards
|
||||||
|
|
||||||
This document is a general coding standard for contributing to Phabricator,
|
This document is a general coding standard for contributing to Phabricator,
|
||||||
Arcanist, libphutil and Diviner.
|
Arcanist, and Diviner.
|
||||||
|
|
||||||
= Overview =
|
= Overview =
|
||||||
|
|
||||||
|
@ -136,7 +136,7 @@ handling and makes it easier to get right than wrong:
|
||||||
Filesystem::writeFile('file.bak', $data); // Best
|
Filesystem::writeFile('file.bak', $data); // Best
|
||||||
do_something_dangerous();
|
do_something_dangerous();
|
||||||
|
|
||||||
See @{article@libphutil:Command Execution} for details on the APIs used in this
|
See @{article@arcanist:Command Execution} for details on the APIs used in this
|
||||||
example.
|
example.
|
||||||
|
|
||||||
= Documentation, Comments and Formatting =
|
= Documentation, Comments and Formatting =
|
||||||
|
|
|
@ -44,7 +44,7 @@ For instructions on adding new classes, see
|
||||||
Writing Translatable Code
|
Writing Translatable Code
|
||||||
=========================
|
=========================
|
||||||
|
|
||||||
Strings are marked for translation with @{function@libphutil:pht}.
|
Strings are marked for translation with @{function@arcanist:pht}.
|
||||||
|
|
||||||
The `pht()` function takes a string (and possibly some parameters) and returns
|
The `pht()` function takes a string (and possibly some parameters) and returns
|
||||||
the translated version of that string in the current viewer's locale, if a
|
the translated version of that string in the current viewer's locale, if a
|
||||||
|
@ -68,7 +68,7 @@ the major rules are:
|
||||||
- Use parameters to create strings containing user names, object names, etc.
|
- Use parameters to create strings containing user names, object names, etc.
|
||||||
- Translate full sentences, not sentence fragments.
|
- Translate full sentences, not sentence fragments.
|
||||||
- Let the translation framework handle plural rules.
|
- Let the translation framework handle plural rules.
|
||||||
- Use @{class@libphutil:PhutilNumber} for numbers.
|
- Use @{class@arcanist:PhutilNumber} for numbers.
|
||||||
- Let the translation framework handle subject gender rules.
|
- Let the translation framework handle subject gender rules.
|
||||||
- Translate all human-readable text, even exceptions and error messages.
|
- Translate all human-readable text, even exceptions and error messages.
|
||||||
|
|
||||||
|
@ -323,7 +323,7 @@ pronouns (like "he" and "she") but there are more complex rules in other
|
||||||
languages, and languages like Czech also require verb agreement.
|
languages, and languages like Czech also require verb agreement.
|
||||||
|
|
||||||
When a parameter refers to a gendered person, pass an object which implements
|
When a parameter refers to a gendered person, pass an object which implements
|
||||||
@{interface@libphutil:PhutilPerson} to `pht()` so translators can provide
|
@{interface@arcanist:PhutilPerson} to `pht()` so translators can provide
|
||||||
gendered translation variants.
|
gendered translation variants.
|
||||||
|
|
||||||
```lang=php
|
```lang=php
|
||||||
|
@ -361,8 +361,8 @@ all human-readable text. This rule is unambiguous and easy to follow.
|
||||||
In cases where similar error or exception text is often repeated, it is
|
In cases where similar error or exception text is often repeated, it is
|
||||||
probably appropriate to define an exception for that category of error rather
|
probably appropriate to define an exception for that category of error rather
|
||||||
than write the text out repeatedly, anyway. Two examples are
|
than write the text out repeatedly, anyway. Two examples are
|
||||||
@{class@libphutil:PhutilInvalidStateException} and
|
@{class@arcanist:PhutilInvalidStateException} and
|
||||||
@{class@libphutil:PhutilMethodNotImplementedException}, which mostly exist to
|
@{class@arcanist:PhutilMethodNotImplementedException}, which mostly exist to
|
||||||
produce a consistent message about a common error state in a convenient way.
|
produce a consistent message about a common error state in a convenient way.
|
||||||
|
|
||||||
There are a handful of error strings in the codebase which may be used before
|
There are a handful of error strings in the codebase which may be used before
|
||||||
|
|
|
@ -2,13 +2,13 @@
|
||||||
@group standards
|
@group standards
|
||||||
|
|
||||||
This document describes PHP coding standards for Phabricator and related
|
This document describes PHP coding standards for Phabricator and related
|
||||||
projects (like Arcanist and libphutil).
|
projects (like Arcanist).
|
||||||
|
|
||||||
= Overview =
|
= Overview =
|
||||||
|
|
||||||
This document outlines technical and style guidelines which are followed in
|
This document outlines technical and style guidelines which are followed in
|
||||||
libphutil. Contributors should also follow these guidelines. Many of these
|
Phabricator and Arcanist. Contributors should also follow these guidelines.
|
||||||
guidelines are automatically enforced by lint.
|
Many of these guidelines are automatically enforced by lint.
|
||||||
|
|
||||||
These guidelines are essentially identical to the Facebook guidelines, since I
|
These guidelines are essentially identical to the Facebook guidelines, since I
|
||||||
basically copy-pasted them. If you are already familiar with the Facebook
|
basically copy-pasted them. If you are already familiar with the Facebook
|
||||||
|
|
|
@ -13,13 +13,13 @@ pipeline, and the browser will treat it as plain text, not HTML.
|
||||||
This document describes the right way to build HTML components so they are safe
|
This document describes the right way to build HTML components so they are safe
|
||||||
from XSS and render correctly. Broadly:
|
from XSS and render correctly. Broadly:
|
||||||
|
|
||||||
- Use @{function@libphutil:phutil_tag} (and @{function:javelin_tag}) to build
|
- Use @{function@arcanist:phutil_tag} (and @{function:javelin_tag}) to build
|
||||||
tags.
|
tags.
|
||||||
- Use @{function@libphutil:hsprintf} where @{function@libphutil:phutil_tag}
|
- Use @{function@arcanist:hsprintf} where @{function@arcanist:phutil_tag}
|
||||||
is awkward.
|
is awkward.
|
||||||
- Combine elements with arrays, not string concatenation.
|
- Combine elements with arrays, not string concatenation.
|
||||||
- @{class:AphrontView} subclasses should return a
|
- @{class:AphrontView} subclasses should return a
|
||||||
@{class@libphutil:PhutilSafeHTML} object from their `render()` method.
|
@{class@arcanist:PhutilSafeHTML} object from their `render()` method.
|
||||||
- @{class:AphrontView} subclasses act like tags when rendering.
|
- @{class:AphrontView} subclasses act like tags when rendering.
|
||||||
- @{function:pht} has some special rules.
|
- @{function:pht} has some special rules.
|
||||||
- There are some other things that you should be aware of.
|
- There are some other things that you should be aware of.
|
||||||
|
@ -28,7 +28,7 @@ See below for discussion.
|
||||||
|
|
||||||
= Building Tags: phutil_tag() =
|
= Building Tags: phutil_tag() =
|
||||||
|
|
||||||
Build HTML tags with @{function@libphutil:phutil_tag}. For example:
|
Build HTML tags with @{function@arcanist:phutil_tag}. For example:
|
||||||
|
|
||||||
phutil_tag(
|
phutil_tag(
|
||||||
'div',
|
'div',
|
||||||
|
@ -37,10 +37,10 @@ Build HTML tags with @{function@libphutil:phutil_tag}. For example:
|
||||||
),
|
),
|
||||||
$content);
|
$content);
|
||||||
|
|
||||||
@{function@libphutil:phutil_tag} will properly escape the content and all the
|
@{function@arcanist:phutil_tag} will properly escape the content and all the
|
||||||
attributes, and return a @{class@libphutil:PhutilSafeHTML} object. The rendering
|
attributes, and return a @{class@arcanist:PhutilSafeHTML} object. The rendering
|
||||||
pipeline knows that this object represents a properly escaped HTML tag. This
|
pipeline knows that this object represents a properly escaped HTML tag. This
|
||||||
allows @{function@libphutil:phutil_tag} to render tags with other tags as
|
allows @{function@arcanist:phutil_tag} to render tags with other tags as
|
||||||
content correctly (without double-escaping):
|
content correctly (without double-escaping):
|
||||||
|
|
||||||
phutil_tag(
|
phutil_tag(
|
||||||
|
@ -52,14 +52,14 @@ content correctly (without double-escaping):
|
||||||
$content));
|
$content));
|
||||||
|
|
||||||
In Phabricator, the @{function:javelin_tag} function is similar to
|
In Phabricator, the @{function:javelin_tag} function is similar to
|
||||||
@{function@libphutil:phutil_tag}, but provides special handling for the
|
@{function@arcanist:phutil_tag}, but provides special handling for the
|
||||||
`sigil` and `meta` attributes.
|
`sigil` and `meta` attributes.
|
||||||
|
|
||||||
= Building Blocks: hsprintf() =
|
= Building Blocks: hsprintf() =
|
||||||
|
|
||||||
Sometimes, @{function@libphutil:phutil_tag} can be particularly awkward to
|
Sometimes, @{function@arcanist:phutil_tag} can be particularly awkward to
|
||||||
use. You can use @{function@libphutil:hsprintf} to build larger and more
|
use. You can use @{function@arcanist:hsprintf} to build larger and more
|
||||||
complex blocks of HTML, when @{function@libphutil:phutil_tag} is a poor fit.
|
complex blocks of HTML, when @{function@arcanist:phutil_tag} is a poor fit.
|
||||||
@{function:hsprintf} has `sprintf()` semantics, but `%s` escapes HTML:
|
@{function:hsprintf} has `sprintf()` semantics, but `%s` escapes HTML:
|
||||||
|
|
||||||
// Safely build fragments or unwieldy blocks.
|
// Safely build fragments or unwieldy blocks.
|
||||||
|
@ -72,13 +72,13 @@ complex blocks of HTML, when @{function@libphutil:phutil_tag} is a poor fit.
|
||||||
- You need to build a block with a lot of tags, like a table with rows and
|
- You need to build a block with a lot of tags, like a table with rows and
|
||||||
cells.
|
cells.
|
||||||
- You need to build part of a tag (usually you should avoid this, but if you
|
- You need to build part of a tag (usually you should avoid this, but if you
|
||||||
do need to, @{function@libphutil:phutil_tag} can not do it).
|
do need to, @{function@arcanist:phutil_tag} can not do it).
|
||||||
|
|
||||||
Note that it is unsafe to provide any user-controlled data to the first
|
Note that it is unsafe to provide any user-controlled data to the first
|
||||||
parameter of @{function@libphutil:hsprintf} (the `sprintf()`-style pattern).
|
parameter of @{function@arcanist:hsprintf} (the `sprintf()`-style pattern).
|
||||||
|
|
||||||
Like @{function@libphutil:phutil_tag}, this function returns a
|
Like @{function@arcanist:phutil_tag}, this function returns a
|
||||||
@{class@libphutil:PhutilSafeHTML} object.
|
@{class@arcanist:PhutilSafeHTML} object.
|
||||||
|
|
||||||
= Composing Tags =
|
= Composing Tags =
|
||||||
|
|
||||||
|
@ -99,7 +99,7 @@ Instead, use an array:
|
||||||
// Render a tag containing other tags safely.
|
// Render a tag containing other tags safely.
|
||||||
phutil_tag('div', array(), array($header, $body));
|
phutil_tag('div', array(), array($header, $body));
|
||||||
|
|
||||||
If you concatenate @{class@libphutil:PhutilSafeHTML} objects, they revert to
|
If you concatenate @{class@arcanist:PhutilSafeHTML} objects, they revert to
|
||||||
normal strings and are no longer marked as properly escaped tags.
|
normal strings and are no longer marked as properly escaped tags.
|
||||||
|
|
||||||
(In the future, these objects may stop converting to strings, but for now they
|
(In the future, these objects may stop converting to strings, but for now they
|
||||||
|
@ -118,7 +118,7 @@ If you need to build a list of items with some element in between each of them
|
||||||
= AphrontView Classes =
|
= AphrontView Classes =
|
||||||
|
|
||||||
Subclasses of @{class:AphrontView} in Phabricator should return a
|
Subclasses of @{class:AphrontView} in Phabricator should return a
|
||||||
@{class@libphutil:PhutilSafeHTML} object. The easiest way to do this is to
|
@{class@arcanist:PhutilSafeHTML} object. The easiest way to do this is to
|
||||||
return `phutil_tag()` or `javelin_tag()`:
|
return `phutil_tag()` or `javelin_tag()`:
|
||||||
|
|
||||||
return phutil_tag('div', ...);
|
return phutil_tag('div', ...);
|
||||||
|
@ -130,8 +130,8 @@ You can use an @{class:AphrontView} subclass like you would a tag:
|
||||||
= Internationalization: pht() =
|
= Internationalization: pht() =
|
||||||
|
|
||||||
The @{function:pht} function has some special rules. If any input to
|
The @{function:pht} function has some special rules. If any input to
|
||||||
@{function:pht} is a @{class@libphutil:PhutilSafeHTML} object, @{function:pht}
|
@{function:pht} is a @{class@arcanist:PhutilSafeHTML} object, @{function:pht}
|
||||||
returns a @{class@libphutil:PhutilSafeHTML} object itself. Otherwise, it returns
|
returns a @{class@arcanist:PhutilSafeHTML} object itself. Otherwise, it returns
|
||||||
normal text.
|
normal text.
|
||||||
|
|
||||||
This is generally safe because translations are not permitted to have more tags
|
This is generally safe because translations are not permitted to have more tags
|
||||||
|
@ -146,23 +146,23 @@ like you would expect, but it is worth being aware of.
|
||||||
NOTE: This section describes dangerous methods which can bypass XSS protections.
|
NOTE: This section describes dangerous methods which can bypass XSS protections.
|
||||||
If possible, do not use them.
|
If possible, do not use them.
|
||||||
|
|
||||||
You can build @{class@libphutil:PhutilSafeHTML} out of a string explicitly by
|
You can build @{class@arcanist:PhutilSafeHTML} out of a string explicitly by
|
||||||
calling @{function:phutil_safe_html} on it. This is **dangerous**, because if
|
calling @{function:phutil_safe_html} on it. This is **dangerous**, because if
|
||||||
you are wrong and the string is not actually safe, you have introduced an XSS
|
you are wrong and the string is not actually safe, you have introduced an XSS
|
||||||
vulnerability. Consequently, you should avoid calling this if possible.
|
vulnerability. Consequently, you should avoid calling this if possible.
|
||||||
|
|
||||||
You can use @{function@libphutil:phutil_escape_html_newlines} to escape HTML
|
You can use @{function@arcanist:phutil_escape_html_newlines} to escape HTML
|
||||||
while converting newlines to `<br />`. You should not need to explicitly use
|
while converting newlines to `<br />`. You should not need to explicitly use
|
||||||
@{function@libphutil:phutil_escape_html} anywhere.
|
@{function@arcanist:phutil_escape_html} anywhere.
|
||||||
|
|
||||||
If you need to apply a string function (such as `trim()`) to safe HTML, use
|
If you need to apply a string function (such as `trim()`) to safe HTML, use
|
||||||
@{method@libphutil:PhutilSafeHTML::applyFunction}.
|
@{method@arcanist:PhutilSafeHTML::applyFunction}.
|
||||||
|
|
||||||
If you need to extract the content of a @{class@libphutil:PhutilSafeHTML}
|
If you need to extract the content of a @{class@arcanist:PhutilSafeHTML}
|
||||||
object, you should call `getHTMLContent()`, not cast it to a string. Eventually,
|
object, you should call `getHTMLContent()`, not cast it to a string. Eventually,
|
||||||
we would like to remove the string cast entirely.
|
we would like to remove the string cast entirely.
|
||||||
|
|
||||||
Functions @{function@libphutil:phutil_tag} and @{function@libphutil:hsprintf}
|
Functions @{function@arcanist:phutil_tag} and @{function@arcanist:hsprintf}
|
||||||
are not safe if you pass the user input for the tag or attribute name. All the
|
are not safe if you pass the user input for the tag or attribute name. All the
|
||||||
following examples are dangerous:
|
following examples are dangerous:
|
||||||
|
|
||||||
|
|
|
@ -1,13 +1,13 @@
|
||||||
@title Writing Unit Tests
|
@title Writing Unit Tests
|
||||||
@group developer
|
@group developer
|
||||||
|
|
||||||
Simple guide to libphutil, Arcanist and Phabricator unit tests.
|
Simple guide to Arcanist and Phabricator unit tests.
|
||||||
|
|
||||||
= Overview =
|
= Overview =
|
||||||
|
|
||||||
libphutil, Arcanist and Phabricator provide and use a simple unit test
|
Arcanist and Phabricator provide and use a simple unit test framework. This
|
||||||
framework. This document is aimed at project contributors and describes how to
|
document is aimed at project contributors and describes how to use it to add
|
||||||
use it to add and run tests in these projects or other libphutil libraries.
|
and run tests in these projects or other libphutil libraries.
|
||||||
|
|
||||||
In the general case, you can integrate `arc` with a custom unit test engine
|
In the general case, you can integrate `arc` with a custom unit test engine
|
||||||
(like PHPUnit or any other unit testing library) to run tests in other projects.
|
(like PHPUnit or any other unit testing library) to run tests in other projects.
|
||||||
|
@ -16,7 +16,7 @@ for information on customizing engines.
|
||||||
|
|
||||||
= Adding Tests =
|
= Adding Tests =
|
||||||
|
|
||||||
To add new tests to a libphutil, Arcanist or Phabricator module:
|
To add new tests to a Arcanist or Phabricator module:
|
||||||
|
|
||||||
- Create a `__tests__/` directory in the module if it doesn't exist yet.
|
- Create a `__tests__/` directory in the module if it doesn't exist yet.
|
||||||
- Add classes to the `__tests__/` directory which extend from
|
- Add classes to the `__tests__/` directory which extend from
|
||||||
|
|
|
@ -18,7 +18,7 @@ If you merge a list of arrays like this:
|
||||||
intermediate arrays and copies every element it has previously seen each time
|
intermediate arrays and copies every element it has previously seen each time
|
||||||
you iterate.
|
you iterate.
|
||||||
|
|
||||||
In a libphutil environment, you can use @{function@libphutil:array_mergev}
|
In a libphutil environment, you can use @{function@arcanist:array_mergev}
|
||||||
instead.
|
instead.
|
||||||
|
|
||||||
= `var_export()` Hates Baby Animals =
|
= `var_export()` Hates Baby Animals =
|
||||||
|
@ -147,7 +147,7 @@ keys that are naturally sortable with a function that uses native comparison
|
||||||
instead, and use it to reorder the original array.
|
instead, and use it to reorder the original array.
|
||||||
|
|
||||||
In a libphutil environment, you can often do this easily with
|
In a libphutil environment, you can often do this easily with
|
||||||
@{function@libphutil:isort} or @{function@libphutil:msort}.
|
@{function@arcanist:isort} or @{function@arcanist:msort}.
|
||||||
|
|
||||||
= `array_intersect()` and `array_diff()` are Also Slow =
|
= `array_intersect()` and `array_diff()` are Also Slow =
|
||||||
|
|
||||||
|
@ -270,7 +270,7 @@ new $class_name($argv[0], $argv[1], ...);
|
||||||
|
|
||||||
...you'll probably invent a very interesting, very novel solution that is very
|
...you'll probably invent a very interesting, very novel solution that is very
|
||||||
wrong. In a libphutil environment, solve this problem with
|
wrong. In a libphutil environment, solve this problem with
|
||||||
@{function@libphutil:newv}. Elsewhere, copy `newv()`'s implementation.
|
@{function@arcanist:newv}. Elsewhere, copy `newv()`'s implementation.
|
||||||
|
|
||||||
= Equality is not Transitive =
|
= Equality is not Transitive =
|
||||||
|
|
||||||
|
|
|
@ -65,7 +65,7 @@ daemonizing it, so you can see output in your console.
|
||||||
|
|
||||||
You can get a list of launchable daemons with **phd list**:
|
You can get a list of launchable daemons with **phd list**:
|
||||||
|
|
||||||
- **libphutil test daemons** are not generally useful unless you are
|
- **test daemons** are not generally useful unless you are
|
||||||
developing daemon infrastructure or debugging a daemon problem;
|
developing daemon infrastructure or debugging a daemon problem;
|
||||||
- **PhabricatorTaskmasterDaemon** performs work from a task queue;
|
- **PhabricatorTaskmasterDaemon** performs work from a task queue;
|
||||||
- **PhabricatorRepositoryPullLocalDaemon** daemons track repositories, for
|
- **PhabricatorRepositoryPullLocalDaemon** daemons track repositories, for
|
||||||
|
|
|
@ -32,7 +32,7 @@ authority and clients have a list of trusted authorities.
|
||||||
You can self-sign a certificate by creating your own CA, but clients will not
|
You can self-sign a certificate by creating your own CA, but clients will not
|
||||||
trust it by default. They need to add the CA as a trusted authority.
|
trust it by default. They need to add the CA as a trusted authority.
|
||||||
|
|
||||||
For instructions on adding CAs, see `libphutil/resources/ssl/README`.
|
For instructions on adding CAs, see `arcanist/resources/ssl/README`.
|
||||||
|
|
||||||
If you'd prefer that `arc` not verify the identity of the server whatsoever, you
|
If you'd prefer that `arc` not verify the identity of the server whatsoever, you
|
||||||
can use the `https.blindly-trust-domains` setting. This will make it
|
can use the `https.blindly-trust-domains` setting. This will make it
|
||||||
|
|
|
@ -48,7 +48,7 @@ Plugin: Error Log
|
||||||
|
|
||||||
The "Error Log" plugin shows errors that occurred while generating the page,
|
The "Error Log" plugin shows errors that occurred while generating the page,
|
||||||
similar to the httpd `error.log`. You can send information to the error log
|
similar to the httpd `error.log`. You can send information to the error log
|
||||||
explicitly with the @{function@libphutil:phlog} function.
|
explicitly with the @{function@arcanist:phlog} function.
|
||||||
|
|
||||||
If errors occurred, a red dot will appear on the plugin tab.
|
If errors occurred, a red dot will appear on the plugin tab.
|
||||||
|
|
||||||
|
|
|
@ -90,15 +90,8 @@ have PHP installed, you can download it from <http://www.php.net/>.
|
||||||
|
|
||||||
To install Arcanist, pick an install directory and clone the code from GitHub:
|
To install Arcanist, pick an install directory and clone the code from GitHub:
|
||||||
|
|
||||||
some_install_path/ $ git clone https://github.com/phacility/libphutil.git
|
|
||||||
some_install_path/ $ git clone https://github.com/phacility/arcanist.git
|
some_install_path/ $ git clone https://github.com/phacility/arcanist.git
|
||||||
|
|
||||||
This should leave you with a directory structure like this
|
|
||||||
|
|
||||||
some_install_path/ # Wherever you chose to install it.
|
|
||||||
arcanist/ # Arcanist-specific code and libraries.
|
|
||||||
libphutil/ # A shared library Arcanist depends upon.
|
|
||||||
|
|
||||||
Now add `some_install_path/arcanist/bin/` to your PATH environment variable.
|
Now add `some_install_path/arcanist/bin/` to your PATH environment variable.
|
||||||
When you type "arc", you should see something like this:
|
When you type "arc", you should see something like this:
|
||||||
|
|
||||||
|
@ -110,8 +103,7 @@ trouble getting this far, see these detailed guides:
|
||||||
- On Windows: @{article:Arcanist User Guide: Windows}
|
- On Windows: @{article:Arcanist User Guide: Windows}
|
||||||
- On Mac OS X: @{article:Arcanist User Guide: Mac OS X}
|
- On Mac OS X: @{article:Arcanist User Guide: Mac OS X}
|
||||||
|
|
||||||
You can later upgrade Arcanist and libphutil to the latest versions with
|
You can later upgrade Arcanist to the latest version with `arc upgrade`:
|
||||||
`arc upgrade`:
|
|
||||||
|
|
||||||
$ arc upgrade
|
$ arc upgrade
|
||||||
|
|
||||||
|
@ -122,7 +114,7 @@ installed and keep people up to date. Here are some approaches you might be
|
||||||
able to use:
|
able to use:
|
||||||
|
|
||||||
- Facebook does most development on development servers, which have a standard
|
- Facebook does most development on development servers, which have a standard
|
||||||
environment and NFS mounts. Arcanist and libphutil themselves live on an
|
environment and NFS mounts. Arcanist lives on an
|
||||||
NFS mount, and the default `.bashrc` adds them to the PATH. Updating the
|
NFS mount, and the default `.bashrc` adds them to the PATH. Updating the
|
||||||
mount source updates everyone's versions, and new employees have a working
|
mount source updates everyone's versions, and new employees have a working
|
||||||
`arc` when they first log in.
|
`arc` when they first log in.
|
||||||
|
|
|
@ -27,9 +27,9 @@ to `src/some/file.php` and give you a detailed coverage report.
|
||||||
If the test engine enables coverage by default, it will be uploaded to
|
If the test engine enables coverage by default, it will be uploaded to
|
||||||
Differential and displayed in the right gutter when viewing diffs.
|
Differential and displayed in the right gutter when viewing diffs.
|
||||||
|
|
||||||
= Enabling Coverage for libphutil, Arcanist and Phabricator =
|
= Enabling Coverage for Arcanist and Phabricator =
|
||||||
|
|
||||||
If you're contributing, libphutil, Arcanist and Phabricator support coverage if
|
If you're contributing, Arcanist and Phabricator support coverage if
|
||||||
you install Xdebug:
|
you install Xdebug:
|
||||||
|
|
||||||
http://xdebug.org/
|
http://xdebug.org/
|
||||||
|
|
|
@ -20,9 +20,6 @@ First, install dependencies:
|
||||||
|
|
||||||
Then install Arcanist itself:
|
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
|
somewhere/ $ git clone https://github.com/phacility/arcanist.git
|
||||||
|
|
||||||
Add `arc` to your path:
|
Add `arc` to your path:
|
||||||
|
|
|
@ -19,8 +19,7 @@ The primary ways to make Conduit calls are:
|
||||||
the API and making calls. This is the best starting point for learning about
|
the API and making calls. This is the best starting point for learning about
|
||||||
the API. See the next section for details.
|
the API. See the next section for details.
|
||||||
|
|
||||||
`ConduitClient`: This is the official client available in `libphutil`, and
|
`ConduitClient`: This is the official client available in `arcanist`.
|
||||||
the one used by `arc`.
|
|
||||||
|
|
||||||
`arc call-conduit`: You can use this `arc` command to execute low-level
|
`arc call-conduit`: You can use this `arc` command to execute low-level
|
||||||
Conduit calls by piping JSON in to stdin. This can provide a simple way
|
Conduit calls by piping JSON in to stdin. This can provide a simple way
|
||||||
|
|
|
@ -55,10 +55,9 @@ If you choose to assign a callsign to a repository, it must be unique within an
|
||||||
install but do not need to be globally unique, so you are free to use the
|
install but do not need to be globally unique, so you are free to use the
|
||||||
single-letter callsigns for brevity. For example, Facebook uses "E" for the
|
single-letter callsigns for brevity. For example, Facebook uses "E" for the
|
||||||
Engineering repository, "O" for the Ops repository, "Y" for a Yum package
|
Engineering repository, "O" for the Ops repository, "Y" for a Yum package
|
||||||
repository, and so on, while Phabricator uses "P", "ARC", "PHU" for libphutil,
|
repository, and so on, while Phabricator uses "P" and Arcanist uses "ARC".
|
||||||
and "J" for Javelin. Keeping callsigns brief will make them easier to use, and
|
Keeping callsigns brief will make them easier to use, and the use of
|
||||||
the use of one-character callsigns is encouraged if they are reasonably
|
one-character callsigns is encouraged if they are reasonably evocative.
|
||||||
evocative.
|
|
||||||
|
|
||||||
If you configure a callsign like `XYZ`, Phabricator will activate callsign URIs
|
If you configure a callsign like `XYZ`, Phabricator will activate callsign URIs
|
||||||
and activate the callsign identifier (like `rXYZ`) for the repository. These
|
and activate the callsign identifier (like `rXYZ`) for the repository. These
|
||||||
|
|
|
@ -83,8 +83,8 @@ You can configure some more options by going to {nav Diffusion > (Select
|
||||||
You can leave this blank for "All languages".
|
You can leave this blank for "All languages".
|
||||||
- **Uses Symbols From**: If this project depends on other repositories, add
|
- **Uses Symbols From**: If this project depends on other repositories, add
|
||||||
the other repositories which symbols should be looked for here. For example,
|
the other repositories which symbols should be looked for here. For example,
|
||||||
Phabricator lists "Arcanist" and "libphutil" because it uses classes and
|
Phabricator lists "Arcanist" because it uses classes and functions defined
|
||||||
functions from these repositories.
|
in `arcanist/`.
|
||||||
|
|
||||||
== External Symbols ==
|
== External Symbols ==
|
||||||
|
|
||||||
|
|
|
@ -41,7 +41,7 @@ installing software on hosts. You'll need to make sure any hosts are configured
|
||||||
properly with any software you need, and have tools like `git`, `hg` or `svn`
|
properly with any software you need, and have tools like `git`, `hg` or `svn`
|
||||||
that may be required to interact with working copies.
|
that may be required to interact with working copies.
|
||||||
|
|
||||||
You do **not** need to install PHP, arcanist, libphutil or Phabricator on the
|
You do **not** need to install PHP, arcanist, or Phabricator on the
|
||||||
hosts unless you are specifically running `arc` commands.
|
hosts unless you are specifically running `arc` commands.
|
||||||
|
|
||||||
**You must configure authentication.** Drydock also does not handle credentials
|
**You must configure authentication.** Drydock also does not handle credentials
|
||||||
|
|
|
@ -23,7 +23,7 @@ the most direct and powerful way to respond to events.
|
||||||
|
|
||||||
To install event listeners in Phabricator, follow these steps:
|
To install event listeners in Phabricator, follow these steps:
|
||||||
|
|
||||||
- Write a listener class which extends @{class@libphutil:PhutilEventListener}.
|
- Write a listener class which extends @{class@arcanist:PhutilEventListener}.
|
||||||
- Add it to a libphutil library, or create a new library (for instructions,
|
- Add it to a libphutil library, or create a new library (for instructions,
|
||||||
see @{article@phabcontrib:Adding New Classes}.
|
see @{article@phabcontrib:Adding New Classes}.
|
||||||
- Configure Phabricator to load the library by adding it to `load-libraries`
|
- Configure Phabricator to load the library by adding it to `load-libraries`
|
||||||
|
@ -40,7 +40,7 @@ see any events the page emitted there. For details on DarkConsole, see
|
||||||
|
|
||||||
To install event listeners in Arcanist, follow these steps:
|
To install event listeners in Arcanist, follow these steps:
|
||||||
|
|
||||||
- Write a listener class which extends @{class@libphutil:PhutilEventListener}.
|
- Write a listener class which extends @{class@arcanist:PhutilEventListener}.
|
||||||
- Add it to a libphutil library, or create a new library (for instructions,
|
- Add it to a libphutil library, or create a new library (for instructions,
|
||||||
see @{article@phabcontrib:Adding New Classes}.
|
see @{article@phabcontrib:Adding New Classes}.
|
||||||
- Configure Phabricator to load the library by adding it to `load`
|
- Configure Phabricator to load the library by adding it to `load`
|
||||||
|
|
|
@ -22,48 +22,6 @@ options:
|
||||||
Encodings" below). This is not completely supported, and repositories with
|
Encodings" below). This is not completely supported, and repositories with
|
||||||
files that have multiple encodings are not supported.
|
files that have multiple encodings are not supported.
|
||||||
|
|
||||||
= Detecting and Repairing Files =
|
|
||||||
|
|
||||||
It is recommended that you write source files only in ASCII text, but
|
|
||||||
Phabricator fully supports UTF-8 source files.
|
|
||||||
|
|
||||||
If you have a project which isn't valid UTF-8 because a few files have random
|
|
||||||
binary nonsense in them, there is a script in libphutil which can help you
|
|
||||||
identify and fix them:
|
|
||||||
|
|
||||||
project/ $ libphutil/scripts/utils/utf8.php
|
|
||||||
|
|
||||||
Generally, run this script on all source files with "-t" to find files with bad
|
|
||||||
byte ranges, and then run it without "-t" on each file to identify where there
|
|
||||||
are problems. For example:
|
|
||||||
|
|
||||||
project/ $ find . -type f -name '*.c' -print0 | xargs -0 -n256 ./utf8 -t
|
|
||||||
./hello_world.c
|
|
||||||
|
|
||||||
If this script exits without output, you're in good shape and all the files that
|
|
||||||
were identified are valid UTF-8. If it found some problems, you need to repair
|
|
||||||
them. You can identify the specific problems by omitting the "-t" flag:
|
|
||||||
|
|
||||||
project/ $ ./utf8.php hello_world.c
|
|
||||||
FAIL hello_world.c
|
|
||||||
|
|
||||||
3 main()
|
|
||||||
4 {
|
|
||||||
5 printf ("Hello World<0xE9><0xD6>!\n");
|
|
||||||
6 }
|
|
||||||
7
|
|
||||||
|
|
||||||
This shows the offending bytes on line 5 (in the actual console display, they'll
|
|
||||||
be highlighted). Often a codebase will mostly be valid UTF-8 but have a few
|
|
||||||
scattered files that have other things in them, like curly quotes which someone
|
|
||||||
copy-pasted from Word into a comment. In these cases, you can just manually
|
|
||||||
identify and fix the problems pretty easily.
|
|
||||||
|
|
||||||
If you have a prohibitively large number of UTF-8 issues in your source code,
|
|
||||||
Phabricator doesn't include any default tools to help you process them in a
|
|
||||||
systematic way. You could hack up `utf8.php` as a starting point, or use other
|
|
||||||
tools to batch-process your source files.
|
|
||||||
|
|
||||||
= Support for Alternate Encodings =
|
= Support for Alternate Encodings =
|
||||||
|
|
||||||
Phabricator has some support for encodings other than UTF-8.
|
Phabricator has some support for encodings other than UTF-8.
|
||||||
|
|
|
@ -66,7 +66,8 @@ abstract class PhabricatorWorkerTask extends PhabricatorWorkerDAO {
|
||||||
$class = $this->getTaskClass();
|
$class = $this->getTaskClass();
|
||||||
|
|
||||||
try {
|
try {
|
||||||
// NOTE: If the class does not exist, libphutil will throw an exception.
|
// NOTE: If the class does not exist, the autoloader will throw an
|
||||||
|
// exception.
|
||||||
class_exists($class);
|
class_exists($class);
|
||||||
} catch (PhutilMissingSymbolException $ex) {
|
} catch (PhutilMissingSymbolException $ex) {
|
||||||
throw new PhabricatorWorkerPermanentFailureException(
|
throw new PhabricatorWorkerPermanentFailureException(
|
||||||
|
|
|
@ -116,7 +116,7 @@
|
||||||
* $pugs = $dog->loadAllWhere('breed = %s', 'Pug');
|
* $pugs = $dog->loadAllWhere('breed = %s', 'Pug');
|
||||||
* $sawyer = $dog->loadOneWhere('name = %s', 'Sawyer');
|
* $sawyer = $dog->loadOneWhere('name = %s', 'Sawyer');
|
||||||
*
|
*
|
||||||
* These methods work like @{function@libphutil:queryfx}, but only take half of
|
* These methods work like @{function@arcanist:queryfx}, but only take half of
|
||||||
* a query (the part after the WHERE keyword). Lisk will handle the connection,
|
* a query (the part after the WHERE keyword). Lisk will handle the connection,
|
||||||
* columns, and object construction; you are responsible for the rest of it.
|
* columns, and object construction; you are responsible for the rest of it.
|
||||||
* @{method:loadAllWhere} returns a list of objects, while
|
* @{method:loadAllWhere} returns a list of objects, while
|
||||||
|
|
|
@ -67,7 +67,7 @@ final class PhabricatorStartup {
|
||||||
*/
|
*/
|
||||||
public static function getMicrosecondsSinceStart() {
|
public static function getMicrosecondsSinceStart() {
|
||||||
// This is the same as "phutil_microseconds_since()", but we may not have
|
// This is the same as "phutil_microseconds_since()", but we may not have
|
||||||
// loaded libphutil yet.
|
// loaded libraries yet.
|
||||||
return (int)(1000000 * (microtime(true) - self::getStartTime()));
|
return (int)(1000000 * (microtime(true) - self::getStartTime()));
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
|
@ -124,7 +124,7 @@ This has a wide array of technical and architectural problems:
|
||||||
the full power of arbitrary JS execution.
|
the full power of arbitrary JS execution.
|
||||||
- It's utterly hideous.
|
- It's utterly hideous.
|
||||||
|
|
||||||
In 2007/2008, we introduced @{function@libphutil:jsprintf} and a function called
|
In 2007/2008, we introduced @{function@arcanist:jsprintf} and a function called
|
||||||
onloadRegister() to solve some of the obvious problems:
|
onloadRegister() to solve some of the obvious problems:
|
||||||
|
|
||||||
lang=php
|
lang=php
|
||||||
|
|
|
@ -1,82 +0,0 @@
|
||||||
@title Javelin at Facebook
|
|
||||||
@group facebook
|
|
||||||
|
|
||||||
Information specific to Javelin at Facebook.
|
|
||||||
|
|
||||||
= Building Support Scripts =
|
|
||||||
|
|
||||||
Javelin now ships with the source to build several libfbjs-based binaries, which
|
|
||||||
serve to completely sever its dependencies on trunk:
|
|
||||||
|
|
||||||
- `javelinsymbols`: used for lint
|
|
||||||
- `jsast`: used for documentation generation
|
|
||||||
- `jsxmin`: used to crush packages
|
|
||||||
|
|
||||||
To build these, first build libfbjs:
|
|
||||||
|
|
||||||
javelin/ $ cd externals/libfbjs
|
|
||||||
javelin/externals/libfbjs/ $ CXX=/usr/bin/g++ make
|
|
||||||
|
|
||||||
Note that **you must specify CXX explicitly because the default CXX is broken**.
|
|
||||||
|
|
||||||
Now you should be able to build the individual binaries:
|
|
||||||
|
|
||||||
javelin/ $ cd support/javelinsymbols
|
|
||||||
javelin/support/javelinsymbols $ CXX=/usr/bin/g++ make
|
|
||||||
|
|
||||||
javelin/ $ cd support/jsast
|
|
||||||
javelin/support/jsast $ CXX=/usr/bin/g++ make
|
|
||||||
|
|
||||||
javelin/ $ cd support/jsxmin
|
|
||||||
javelin/support/jsxmin $ CXX=/usr/bin/g++ make
|
|
||||||
|
|
||||||
= Synchronizing Javelin =
|
|
||||||
|
|
||||||
To synchronize Javelin **from** Facebook trunk, run the synchronize script:
|
|
||||||
|
|
||||||
javelin/ $ ./scripts/sync-from-facebook.php ~/www
|
|
||||||
|
|
||||||
...where `~/www` is the root you want to pull Javelin files from. The script
|
|
||||||
will copy files out of `html/js/javelin` and build packages, and leave the
|
|
||||||
results in your working copy. From there you can review changes and commit, and
|
|
||||||
then push, diff, or send a pull request.
|
|
||||||
|
|
||||||
To synchronize Javelin **to** Facebook trunk, run the, uh, reverse-synchronize
|
|
||||||
script:
|
|
||||||
|
|
||||||
javelin/ $ ./scripts/sync-to-facebook.php ~/www
|
|
||||||
|
|
||||||
...where `~/www` is the root you want to push Javelin files to. The script
|
|
||||||
will copy files out of the working copy into your `www` and leave you with a
|
|
||||||
dirty `www`. From there you can review changes.
|
|
||||||
|
|
||||||
Once Facebook moves to pure git for `www` we can probably just submodule
|
|
||||||
Javelin into it and get rid of all this nonsense, but the mixed SVN/git
|
|
||||||
environment makes that difficult until then.
|
|
||||||
|
|
||||||
= Building Documentation =
|
|
||||||
|
|
||||||
Check out `diviner` and `libphutil` from Facebook github, and put them in a
|
|
||||||
directory with `javelin`:
|
|
||||||
|
|
||||||
somewhere/ $ ls
|
|
||||||
diviner/
|
|
||||||
javelin/
|
|
||||||
libphutil/
|
|
||||||
somewhere/ $
|
|
||||||
|
|
||||||
Now run `diviner` on `javelin`:
|
|
||||||
|
|
||||||
somewhere/ $ cd javelin
|
|
||||||
somewhere/javelin/ $ ../diviner/bin/diviner .
|
|
||||||
[DivinerArticleEngine] Generating documentation for 48 files...
|
|
||||||
[JavelinDivinerEngine] Generating documentation for 74 files...
|
|
||||||
somewhere/javelin/ $
|
|
||||||
|
|
||||||
Documentation is now available in `javelin/docs/`.
|
|
||||||
|
|
||||||
= Editing javelinjs.com =
|
|
||||||
|
|
||||||
The source for javelinjs.com lives in `javelin/support/webroot/`. The site
|
|
||||||
itself is served off the phabricator.com host. You need access to that host to
|
|
||||||
push it.
|
|
Loading…
Reference in a new issue