------------------- Getting Started with Debugger -------------------


1. Quick Overview

(1) from A to Z

All built-in debugger commands are un-ambiguous with their first
letters. Therefore, a single letter is sufficient to issue the command.

(2) tab, tab, tab

Use TAB to auto-complete.

(3) input PHP code

For single line of PHP code, use "=" to print an expression's value, OR,
use "@" to execute an expression or statement without printing return
values, OR, start an assignment with "$" variable name.

For multi-line PHP code, type "<" then TAB. Now you can type or paste
multiple lines of code. Hit return to start a new line, then TAB. That
will auto-complete "?>" to finish the block. Hit return to execute.

(4) help

Use "help" to read more about command details.

(5) info and list

Use "info" and "list" commands to read more about source code.

(6) readline

Debugger is written with readline library, which has rich feature set,
including switching between emacs and vi editing mode. Please read its
[[ http://cnswww.cns.cwru.edu/php/chet/readline/readline.html#SEC1 |
documentation]] for more details.


2. Debugging local script

The command to run a script normally looks like this,

  hhvm myscript.php

Simply add "-m debug" to run the script in debugger,

  hhvm -m debug myscript.php
  
Once started, set breakpoints like this,

  hphpd> break myscript.php:10
  hphpd> break foo()

Then let it run, until it hits the breakpoints,

  hphpd> run

The debugger will highlight current statement or expression that is just
about to evaluate. Sometimes a statement is highlighted first, then
sub-expressions inside the statement are highlighted one after another
while repeating step commands.

At any breakpoints, examine variables or evaluate expressions,

  hphpd> variable
  hphpd> print $a
  hphpd> =$a
  hphpd> <?php print $a; ?>
  hphpd> <?php
   ..... print $a;
   ..... ?>

Optionally, modify variables like this,

  hphpd> $a = 10
  hphpd> <?php $a = 10; ?>
  hphpd> <?php
   ..... $a = 10;
   ..... ?>

Then let it continue, until it hits more breakpoints,

  hphpd> continue

Finally, quit debugger,

  hphpd> quit


3. Debugging sandbox

Connect to an HPHP server from command line,

  hhvm -m debug -h mymachine.com

Or, connect from within debugger,

  hphpd> machine connect mymachine.com

This will try to attach to a default sandbox on that machine.
"Attaching" means it will only debug web requests hitting that sandbox.
To switch to a different sandbox,

  mymachine> machine list
  mymachine> machine attach 2

In remote debugging mode, a breakpoint can be specific about an URL,

  mymachine> break myscript.php:10@index.php
  mymachine> break foo()@index.php

You may connect to more than one machine and breakpoints will be shared
by all of them.


4. Understanding dummy sandbox

When a web request hits a breakpoint, debugger will run in a "Web
Request" thread. Use "thread" command to display this information,

  mymachine> thread

What will debugger use when there is no web request thread that's
active, but we need to set a breakpoint? We created so-called "dummy
sandbox", purely for taking debugger commands when there is no active
web request. When there is no active request, hit Ctrl-C to break into
the debugger, and use "thread" to display dummy sandbox thread's
information.

  Ctrl-C
  mymachine> thread

In dummy sandbox, a PHP file can be pre-loaded, so that we can "info"
functions and classes and execute certain code. This file is specified
on server side by

  Eval.Debugger.StartupDocument = scripts/startup.php

Dummy sandbox will always use currently attached sandbox's PHP files.
When files are modified, simply reload them by

  mymachine> continue
  Ctrl-C


5. Colors and Configuration

By default, it will use emacs colors for dark background. To change
them, run debugger at least once, then look for ~/.hphpd.hdf file.
Replace "Code" node with,

  Color {
    Code : Color.Palette.vim
  }

Or, specify your own colors in different places of the configuration
file.