hphp/doc/debugger.start

   1
   2     ------------------- Getting Started with Debugger -------------------
   3
   4
   5 1. Quick Overview
   6
   7 (1) from A to Z
   8
   9 All built-in debugger commands are un-ambiguous with their first
  10 letters. Therefore, a single letter is sufficient to issue the command.
  11
  12 (2) tab, tab, tab
  13
  14 Use TAB to auto-complete.
  15
  16 (3) input PHP code
  17
  18 For single line of PHP code, use "=" to print an expression's value, OR,
  19 use "@" to execute an expression or statement without printing return
  20 values, OR, start an assignment with "$" variable name.
  21
  22 For multi-line PHP code, type "<" then TAB. Now you can type or paste
  23 multiple lines of code. Hit return to start a new line, then TAB. That
  24 will auto-complete "?>" to finish the block. Hit return to execute.
  25
  26 (4) help
  27
  28 Use "help" to read more about command details.
  29
  30 (5) info and list
  31
  32 Use "info" and "list" commands to read more about source code.
  33
  34 (6) readline
  35
  36 Debugger is written with readline library, which has rich feature set,
  37 including switching between emacs and vi editing mode. Please read its
  38 [[ http://cnswww.cns.cwru.edu/php/chet/readline/readline.html#SEC1 |
  39 documentation]] for more details.
  40
  41
  42 2. Debugging local script
  43
  44 The command to run a script normally looks like this,
  45
  46   hhvm myscript.php
  47
  48 Simply add "-m debug" to run the script in debugger,
  49
  50   hhvm -m debug myscript.php
  51
  52 Once started, set breakpoints like this,
  53
  54   hphpd> break myscript.php:10
  55   hphpd> break foo()
  56
  57 Then let it run, until it hits the breakpoints,
  58
  59   hphpd> run
  60
  61 The debugger will highlight current statement or expression that is just
  62 about to evaluate. Sometimes a statement is highlighted first, then
  63 sub-expressions inside the statement are highlighted one after another
  64 while repeating step commands.
  65
  66 At any breakpoints, examine variables or evaluate expressions,
  67
  68   hphpd> variable
  69   hphpd> print $a
  70   hphpd> =$a
  71   hphpd> <?hh print $a; ?>
  72   hphpd> <?hh
  73    ..... print $a;
  74    ..... ?>
  75
  76 Optionally, modify variables like this,
  77
  78   hphpd> $a = 10
  79   hphpd> <?hh $a = 10; ?>
  80   hphpd> <?hh
  81    ..... $a = 10;
  82    ..... ?>
  83
  84 Then let it continue, until it hits more breakpoints,
  85
  86   hphpd> continue
  87
  88 Finally, quit debugger,
  89
  90   hphpd> quit
  91
  92
  93 3. Debugging sandbox
  94
  95 Connect to an HPHP server from command line,
  96
  97   hhvm -m debug -h mymachine.com
  98
  99 Or, connect from within debugger,
 100
 101   hphpd> machine connect mymachine.com
 102
 103 This will try to attach to a default sandbox on that machine.
 104 "Attaching" means it will only debug web requests hitting that sandbox.
 105 To switch to a different sandbox,
 106
 107   mymachine> machine list
 108   mymachine> machine attach 2
 109
 110 In remote debugging mode, a breakpoint can be specific about an URL,
 111
 112   mymachine> break myscript.php:10@index.php
 113   mymachine> break foo()@index.php
 114
 115 You may connect to more than one machine and breakpoints will be shared
 116 by all of them.
 117
 118
 119 4. Understanding dummy sandbox
 120
 121 When a web request hits a breakpoint, debugger will run in a "Web
 122 Request" thread. Use "thread" command to display this information,
 123
 124   mymachine> thread
 125
 126 What will debugger use when there is no web request thread that's
 127 active, but we need to set a breakpoint? We created so-called "dummy
 128 sandbox", purely for taking debugger commands when there is no active
 129 web request. When there is no active request, hit Ctrl-C to break into
 130 the debugger, and use "thread" to display dummy sandbox thread's
 131 information.
 132
 133   Ctrl-C
 134   mymachine> thread
 135
 136 In dummy sandbox, a PHP file can be pre-loaded, so that we can "info"
 137 functions and classes and execute certain code. This file is specified
 138 on server side by
 139
 140   Eval.Debugger.StartupDocument = scripts/startup.php
 141
 142 Dummy sandbox will always use currently attached sandbox's PHP files.
 143 When files are modified, simply reload them by
 144
 145   mymachine> continue
 146   Ctrl-C
 147
 148
 149 5. Colors and Configuration
 150
 151 By default, it will use emacs colors for dark background. To change
 152 them, run debugger at least once, then look for ~/.hphpd.ini file.
 153 Replace "Code" node with,
 154
 155   Color {
 156     Code : Color.Palette.vim
 157   }
 158
 159 Or, specify your own colors in different places of the configuration
 160 file.
 161