src/docs/contributor/developer_setup.diviner

   1 @title Developer Setup
   2 @group developer
   3
   4 How to configure a Phabricator development environment.
   5
   6 Overview
   7 ========
   8
   9 There are some options and workflows that may be useful if you are developing
  10 or debugging Phabricator.
  11
  12
  13 Configuration
  14 =============
  15
  16 To adjust Phabricator for development:
  17
  18   - Enable `phabricator.developer-mode` to enable some options and show
  19     more debugging information.
  20   - Enable `phabricator.show-prototypes` to show all the incomplete
  21     applications.
  22   - See @{article: Using DarkConsole} for instructions on enabling the
  23     debugging console.
  24
  25
  26 Error Handling
  27 ==============
  28
  29 Errors normally go to DarkConsole (if enabled) and the webserver error log,
  30 which is often located somewhere like `/var/log/apache/error_log`. This file
  31 often contains relevant information after you encounter an error.
  32
  33 When debugging, you can print information to the error log with `phlog(...)`.
  34 You can `phlog(new Exception(...))` to get a stack trace.
  35
  36 You can print information to the UI with `throw new Exception(...)`,
  37 `print_r(...)`, or `var_dump(...)`.
  38
  39 You can abort execution with `die(...)` if you want to make sure execution
  40 does not make it past some point. Normally `throw` does this too, but callers
  41 can `catch` exceptions; they can not catch `die(...)`.
  42
  43
  44 Utilities
  45 =========
  46
  47 After adding, renaming, or moving classes, run `arc liberate` to rebuild
  48 the class map:
  49
  50 ```
  51 phabricator/ $ arc liberate
  52 ```
  53
  54 Until you do this, Phabricator won't recognize your new, moved, or renamed
  55 classes. You do not need to run this after modifying an existing class.
  56
  57 After any modifications to static resources (CSS / JS) but before sending
  58 changes for review or pushing them to the remote, run `bin/celerity map`:
  59
  60 ```
  61 phabricator/ $ ./bin/celerity map
  62 ```
  63
  64 This rebuilds the static resource map.
  65
  66 If you forget to run these commands you'll normally be warned by unit tests,
  67 but knowing about them may prevent confusion before you hit the warnings.
  68
  69
  70 Command Line
  71 ============
  72
  73 Almost every script supports a `--trace` flag, which prints out service
  74 calls and more detailed error information. This is often the best way to get
  75 started with debugging command-line scripts.
  76
  77
  78 Performance
  79 ===========
  80
  81 Although it is more user-focused than developer-focused, the
  82 @{article:Troubleshooting Performance Problems} guide has useful information
  83 on the tools available for diagnosing and understanding performance problems.
  84
  85
  86 Custom Domains
  87 ==============
  88
  89 If you're working with applications that support custom domains (like Phurl or
  90 Phame) you can normally test them by adding more entries to your webserver
  91 configuration that look exactly like the primary entry (or expanding the
  92 primary entry to match more domains).
  93
  94 Phabricator routes all requests based on host headers, so alternate domains
  95 do not normally need any kind of special configuration.
  96
  97 You may also need to add `/etc/hosts` entries for the domains themselves.
  98
  99
 100 Creating Test Data
 101 ==================
 102
 103 You can create test objects with the "Lipsum" utility:
 104
 105 ```
 106 phabricator/ $ ./bin/lipsum help generate
 107 phabricator/ $ ./bin/lipsum generate ...
 108 ```
 109
 110 Test data can make your local install feel a little more realistic. With
 111 `--quickly`, you can generate a large amount of test data to help test issues
 112 with performance or scale.