____
  / __/ __  ___ ___  ___ ___
  _\ \/ _ \/ -_) _ `/ __/ -_)
 /___/ .__/\__/\_,_/_/  \__/
    /_/
Speare Pro v1.2.17
(c) 2019 http://sevenuc.com

Speare is an ultra lightweight code editor and small IDE that has a designedly graphical user operation interface smoothly support editing multiple files that written with different programming languages simultaneously. It was originally developed to provide a native scripting language debugging environment that seamlessly integrated with C and C++. You can use the free version to debug C and C++ project. Speare Pro is the advanced version that has IDE features especially scripting language debugging environment supported. It supports debugging applications that written with C, C++, Ruby, Lua, Python, PHP and Perl. The most important feature of Speare is that it support extend the debuggers by yourself and directly switch between any version of self-compiled scripting language interpreters.

Debugger Index:

C and C++ Debugger
mruby Debugger
Ruby Debugger
Lua Debugger
Python Debugger
PHP Debugger
Perl Debugger




If you can't open the link above, please launch App Store and found Speare Pro by searching.





Debug Mode

1. Click siding bottom button to show the debug toolbar.

2. Debug toolbar:



From left to right: Start, Stop, Step into, Step out, Run to, Step Over (Step Next), Show Watches.

3. Socket port:
You can set the socket communication port number both used by Debug Server and the Speare code editor. Open the Preferences of Speare and select the "Debug Settings" tab then input your number.

4. Watches:
Watches used to evaluate variables or expressions and their values can be real time showing in stackview when debugging, the nodes normally has a green colour.

Warning:
  • a. Please ensure all source files have been dragged in the left side Treeview (Workspace Explorer) before start a debug session, because macOS app can't be allowed to access files outside of its sandbox.
  • b. When your source code file moved to another folder, you must drag the source code folder in Speare again then the debugging can correctly work.

Debugger Architecture




C and C++ Debugger

The C and C++ debugger of Speare code editor implemented as a script client of LLDB, and support extend it by yourself. You can enjoy debugging almost any type of C and C++ applications under the lightweight debugging environment of Speare code editor.

Start Debugging Steps:
1. Download Speare Debug Server: → http://sevenuc.com/download/c_debugger.tar.gz (10KB)
SHA256: a595384b5b4d8d6ae600f2aec3caeaa20dbf40a4d0c0311b00b9549f6265d6c6
The source code of the C and C++ debugger can be view online here:
https://github.com/chengdu/Speare or here: https://sourceforge.net/projects/speare

2. Uncompress the tarball to your local directory. e.g ~/Desktop and take a look at the readme.txt in it.

3. Start the debug server:
Please refer the readme.txt file.

4. Debug session start: click "Start" button on the debug toolbar of Speare code editor.
Add breakpoint, step in, step out, step next, watch stack trace ...

5. Run extra commands:
Right click in the stackview (bottom left side) and then input any lldb command when the debugging session paused. Left click anywhere outside of the input box to close it and the command will be directly send to the debug server.
a. Add function breakpoints
. breakpoint set --name functioname: add a C function breakpoint.
. breakpoint set --name classname::functioname: add a C++ function breakpoint.
b. Process operation
. process attach --name xxx --waitfor: attach another process by name.
. process attach --pid xxx: attach another process by pid #xxx.
c. Thread operation
. thread list: show all thread of current process.
. thread select 2: select thread #2.
. thread backtrace all: show thread info.
. register read: read all CPU registers.
. thread step-inst: step one machine instruction.
. thread step-over-inst: step return one machine instruction.
d. Watchpoint operation
. watch list -v: list watchpoints.
. watchpoint set variable x: add a watchpoint x.
e. Frame operation
. frame list: print all frame of the current thread.
. frame select 9: select frame #9.
f. Display variable value
. frame variable x: print x value.
...

Tips: Run to (run to meet a breakpoint), the source file that you want debugger stopped in it must already opened and has at least one breakpoint before run the command.

6. Modify the C and C++ debugger:
You can directly modify the script client of lldb to satisfy your requirements.

About the C programming language

The product quality of the software industry is directly proportional to the number of experienced C programming experts.


mruby Debugger

The mruby debugger of Speare Pro is a patched version of mruby 2.0.1 that support remote debugging mruby project.

1. Install mruby debugging server

Download mruby remote debugger: → http://sevenuc.com/download/mruby_debugger.tar.gz (362KB)
SHA256: 66c3d9bc35941d01824669bbd873815fa89d2a08b758af84600e17b4e12dda95
Download mruby-2.0.1.tar.gz (518KB) from https://github.com/mruby/mruby
$ cd mruby-2.0.1
$ make: compile mruby and replace mrdb under bin directory with the file in mruby_debugger.tar.gz.
$ cd bin
$ ./mrdb : start the mruby remote debugger.

2. Configuring Speare Pro

Launch Speare Pro and open the Preferences of Speare and select the tab of "Debug Settings" then check on "Enable mruby debugging". Please remember to turn the option off when you switched to debug common Ruby applications.

3. Debug Session Start

Click "Start" button on the debug toolbar of Speare Pro.
Add breakpoint, step in, step out, step next, watch stack trace ...

Tips: Separate modules of your app with mruby gems instead of using require.


Ruby Debugger

The Ruby debugger of Speare Pro implemented as a client of rdebug-ide, and Ruby interpreter that has a rdebug-ide installed will be running as the debug server.

Ruby debugging environment support all kinds of Ruby interpreters, the version includes: 1.8.x, 1.9.x, 2.x, and JRuby.

Steps of start debugging session:

1. Download and install debug gems:

For Ruby 1.8.x: download: ruby-debug-base (0.10.4)
$ gem install --force --local ruby-debug-base-0.10.4.gem
$ gem install ruby-debug-ide

For Ruby 1.9.x: download: ruby-debug-base19 (0.11.25)
$ gem install --force --local ruby-debug-base19x-0.11.32.gem
$ gem install ruby-debug-ide

For Ruby 2.x:
$ gem install debase
$ gem install ruby-debug-ide

2. Start the debug server:

$ rdebug-ide --host 127.0.0.1 --port 1234 --dispatcher-port 1234 -- main.rb
(please replace the main.rb file with your script file.)
For Rails: $ rdebug-ide --host 0.0.0.0 --port 1234 --dispatcher-port 1234 -- bin/rails s

3. Debug session start:
click "Start" button on the debug toolbar of Speare Pro.
Add breakpoint, step in, step out, step next, watch stack trace ...

4. Add condition breakpoint:
Right click on the breakpoint, on the prompt menu, → select "Condition" and then input expression or use empty string to remove the condition, left click outside of the input box to close it and execute the command. e.g. x>5 means: Pause on the breakpoint only if x>5 is true.

5. Run Extra Commands:
Right click in the stackview (bottom left side) and then input extra command when the debugging session paused. Left click anywhere outside of the input box to close it and the command will be directly send to the debug server.

a. Variables
. var const object: show constants of object.
. var instance object: show instance variables of object, object can be given by its id or an expression.
. var inspect: reference inspection results in order to save them from the GC.

b. Expression
. p expression: evaluate expression and print its value.
. pp expression: evaluate expression and print its value.
. eval expression: evaluate expression and print its value, alias for p.
. expression_info expression: returns parser-related information for the expression given 'incomplete'=true | false indicates whether expression is a complete ruby expression and can be evaluated without getting syntax errors.

c. Backtrace
. where: display frames.
. bt | backtrace: alias for where.
. up | down [count]: move to higher or lower frame.
. frame [frame-number]: Move the current frame to the specified frame number. (A negative number indicates position from the other end. So 'frame -1' moves to the oldest frame, and 'frame 0' moves to the newest frame.)

d. Jump
Change the next line of code to be executed.
. jump line: jump to line number (absolute).
. jump -line: jump back to line (relative).
. jump +line: jump ahead to line (relative).

e. Thread
. thread list: list all threads.
. thread current: show current thread.
. thread switch <nnn>: switch thread context to nnn.
. thread inspect <nnn>: switch thread context to nnn but don't resume any threads.
. thread resume <nnn>: resume thread nnn.
. thread stop <nnn>: stop thread nnn.

f. Type Set
. set_type <var> <type>: Change the type of <var> to <type>.

g. File Operation
. load file: read and parse file every time instead of require.
. file-filter on | off: enable or disable file filtering.
. include file | dir: adds file or dir to file filter (either remove already excluded or add as included).
. exclude file | dir: exclude file or dir from file filter (either remove already included or add as exclude).

6. Switch Ruby interpreter:
You can directly switch between any Ruby interpreter or your own version of Ruby and then config it to support rdebug-ide.


Lua Debugger

The Lua debugger of Speare Pro implemented as a module of Lua, and support all common versions of Lua. You can conveniently enjoy debugging with any kinds of customised Lua interpreter and LuaJIT.

Tested Lua version includes: 5.1.4, 5.1.5, 5.2.4, 5.3.5 5.4.0-alpha

Start Debugging Steps:

1. Download Speare Debug Server: → http://sevenuc.com/download/lua_debugger.tar.gz (518KB)
SHA256: a9447cedd668553f0b0eb5c2f5221b6af349dd6cf73602513f98e9b366022c94
2. Uncompress the tarball to your local directory. e.g ~/Desktop and take a look at the readme.txt in it.
3. Start the debug server:

$ cd ~/Desktop/debugger/5.1
$ ./lua_514 server.lua

4. Debug session start: click "Start" button on the debug toolbar of Speare Pro.
Add breakpoint, step in, step out, step next, watch stack trace ...

5. Replace Lua interpreter:
You can directly replace the Lua interpreter with your own customised version under the debugger directory.


Python Debugger

The Python debugger of Speare Pro supports Python version 2.5, 2.6, 2.7 and 3.x, and MicroPython. You can enjoy debugging Python scripts as same as debugging web applications that based on web frameworks such as Flask and Django under the lightweight environment of Speare code editor.

Steps of Start Debugging Session:

1. Download Speare Debug Server: → http://sevenuc.com/download/python_debugger.tar.gz (30KB)
SHA256: 74cc8544671eed3de317305573cc9f1f95ae395533d1f08ce84b248cee883250
The source code of the Python debugger can be view online here:
https://github.com/chengdu/Speare or here: https://sourceforge.net/projects/speare
2. Uncompress the tarball to your local directory. e.g ~/Desktop and take a look at the readme.txt in it.
3. Start the debug server:

$ cd ~/Desktop/debugger/2.x
$ python server.py

4. Debug session start: click "Start" button on the debug toolbar of Speare Pro.
Add breakpoint, step in, step out, step next, watch stack trace ...

5. Add condition breakpoint
Described in the Ruby debug section of this page.

6. Run Extra Commands:

a. Remove all breakpoints
. clear: clear all breakpoints of current file.

b. Stack trace and frame operation
. where: Print stack trace, an arrow indicates the "current frame".
. up [count]: Move stack trace to older frame.
. down [count]: Move stack trace to newer frame.

c. Display argument list
. args: Print the argument list of the current function.

d. Display return value
. retval: Print the return value for the last return of a function.

e. Display value of expression
. p expression: Print the value of the expression.
. pp expression: Pretty-print the value of the expression.
. display expression: Display the value of the expression, Python 3.x only.
. undisplay: Clear all display expressions for the current frame, Python 3.x only.
. undisplay expression: Do not display the expression any more in the current frame, Python 3.x only.

f. Display argument type
. whatis argument: Print the type of the argument.

g. Display source code of object
. source expression: Python 3.x only.

h. Continue execution
. until: continue execution until the line number greater than the current is reached.
. until [lineno]: continue execution until line number greater or equal to the lineno is reached.

i. Add module search path
. basedir directory: insert a directory in sys.path.

7. Switch Python interpreter:
You can directly switch CPython interpreter to MicroPython or your own self-compiled version of Python, or others such as PyPy, Jython and IronPython.


PHP Debugger

The PHP debugger of Speare Pro supports all kinds debugging of PHP applications and any version of PHP interpreter that has Xdebug support from PHP 5.x to PHP 7.x. Different with Lua, Ruby and Python debugging, this time Speare Pro acts as debug server and Xdebug as the client.

Setting up Xdebug for PHP Debugging:

1. Download Xdebug:
https://xdebug.org/files/xdebug-2.6.0.tgz

2. Compile and install Xdebug:
$ rm configure.in (optional)
$ rm configure.ac (optional)
$ phpize && ./configure --enable-xdebug && make clean && make all
$ sudo make install
At this step Terminal will report:

/usr/lib/php/extensions Operation not permitted.

This is because SIP default set to be enabled by macOS, even you execute sudo operation, the system protected directories still can't be writable.

WARNING: THE FOLLOWING OPERATION IS VERY DANGERS.
Assuming that you know what you’re doing, here is how to change SIP (System Integrity Protection) settings on your Mac. Turn off your Mac (Apple → Shut Down...), hold down Command-R and press the Power button. Keep holding Command-R until the Apple logo appears and wait for OS X to boot into the "OS X Utility" window and then choose Utilities → Terminal.

Turn off SIP:
$ csrutil disable
$ csrutil status
$ reboot

Turn on SIP:
$ csrutil enable
$ csrutil status
$ reboot

After you turn off SIP and execute "$ sudo make install" again, Xdebug should be successfully installed on you system, you can check it by this command:
$ php -v
It should print something like the following:

PHP 7.1.23 (cli) (built: Nov 27 2018 16:59:25) ( NTS )
Copyright (c) 1997-2018 The PHP Group
Zend Engine v3.1.0, Copyright (c) 1998-2018 Zend Technologies
with Xdebug v2.6.0, Copyright (c) 2002-2018, by Derick Rethans

3. Configuring web server:
$ cp /etc/apache2/httpd.conf ~/Desktop/

LoadModule userdir_module libexec/apache2/mod_userdir.so
LoadModule alias_module libexec/apache2/mod_alias.so
LoadModule rewrite_module libexec/apache2/mod_rewrite.so
LoadModule php7_module libexec/apache2/libphp7.so
Include /private/etc/apache2/other/*.conf

Edit file http.conf and ensure the above lines not be commented.
$ sudo cp ~/Desktop/httpd.conf /etc/apache2/
Save back the settings file.
$ apachectl configtest
Check there syntax is legal (optional).

4. Configuring PHP interpreter:
$ cp /etc/php.ini.default ~/Desktop/

enable_dl = On
[xdebug]
zend_extension = /usr/lib/php/extensions/no-debug-non-zts-20160303/xdebug.so
xdebug.remote_enable = 1
xdebug.remote_host = "127.0.0.1"
xdebug.remote_port = 9000
xdebug.remote_handler = "dbgp"
xdebug.remote_mode = req
xdebug.remote_connect_back = 1
xdebug.remote_autostart=1

Edit file php.ini.default and carefully check the above content have been written in it.
Note: xdebug.remote_autostart=1 should be removed at product environment.
$ sudo cp ~/Desktop/php.ini.default /etc/
Save back the settings file.
$ sudo mv /etc/php.ini.default /etc/php.ini
Rename the settings file to take effect.

5. Run PHP test with Xdebug:

<?php
echo phpinfo();
?>

Save the above content in a file named test.php and put it under /Library/WebServer/Documents/
$ sudo launchctl unload -w /System/Library/LaunchDaemons/org.apache.httpd.plist
$ sudo launchctl load -w /System/Library/LaunchDaemons/org.apache.httpd.plist
Restart apache, launch Safari and request: http://127.0.0.1/test.php.
There're some text in zend engine section should be as same as printed by execute the command "$ php -v" on command line.

Steps of PHP Debugging with Speare Pro:

1. Launch Speare Pro and dragging the PHP source code folder into the "Workspace Explorer".
2. Select the startup php script and Click siding bottom button to show the debug toolbar and then click "Start" button.
3. Launch Safari and request: http://127.0.0.1/xxx/xxx/index.php

Note: Don't use localhost but should use 127.0.0.1 instead.

4. After Speare Pro paused and highlighting at a special line of your startup PHP script there that means the debugging session started, you can execute the common debugging command now:

Add breakpoint, step in, step out, step next, watch stack trace ...

You can switch any version of PHP interpreter directly, it does not affect the server side Speare Pro. PHP is an excellent programming language to develop Web Applications based on frameworks such as Drupal, Zend Framework, CodeIgniter, Symfony and Yii framework etc, but not limited that, in fact PHP is also very suitable to develop command line applications.


Perl Debugger

The Perl debugger of Speare Pro implemented as a patched version of perl5db.pl, and support extend it by yourself. The debugger was based on the builtin debugger of Perl, so it can work with all versions of Perl interpreter that perl5db.pl supported.

Start Debugging Steps:
1. Download Speare Debug Server: → http://sevenuc.com/download/perl_debugger.tar.gz(104KB)
SHA256: 83f8674ee4dfdf8e8155551d2d8483942ee80b634dd90e362e62c2222744b6b6
The source code of the Perl debugger can be view online here:
https://github.com/chengdu/Speare or here: https://sourceforge.net/projects/speare

2. Uncompress the tarball to your local directory. e.g ~/Desktop and take a look at the readme.txt in it.
3. Start the debug server:

$ cd ~/Desktop/debugger
$ perl -I ~/Desktop/debugger/Speare -d:Debugger fullpath.pl
* Warning: fullpath.pl the file must input with full path.

4. Debug session start: click "Start" button on the debug toolbar of Speare code editor.
Add breakpoint, step in, step out, step next, watch stack trace ...

5. Run extra commands:
Right click in the stackview (bottom left side) and then input any Perl debug command when the debugging session paused. Left click anywhere outside of the input box to close it and the command will be directly send to the debug server.
a. Add function breakpoints
. b functionname: add a function breakpoint.
b. Add condition breakpoints
. via breakpoint marker: Right click on the breakpoint, on the prompt menu, → select "Condition" and then input expression or use empty string to remove the condition, left click outside of the input box to close it and execute the command. e.g. x > 5 means: Pause on the breakpoint only if x > 5 is true.
. b fullpath.pl condition: e.g. b /xxx/xxx/code.pl 6 $x > 5.
/xxx/xxx/code.pl: fullpath of the script file. (do the same thing, optional)
c. Watchpoint operation
. w expr: add a watchpoint expr.
. W expr: delete watchpoint expr.
. W *: delete all watchpoints.
d. Evaluate express
. e expr: e.g. `e $x+$y`.
e. Display variable value
. p $x: print value of variable `x`.
. p expr: print value of expression `expr`.
...

6. Switch Perl interpreter:
You can directly switch the Perl interpreter on the command line or debugging with your own self-compiled version of Perl.

About Perl

Perl was originally developed by Larry Wall in 1987 as a general-purpose Unix scripting language. Thirty years past, it still the most suitable programming language to resolve your problem at some situation, from the server side powerful tool such as load balance to web applications, and large scale enterprise application.

Intellectual Property Transfer

Develop an IDE (Integrated Development Environment) for a special programming language becomes very simple by leveraging the features of Speare code editor. The debug environment of common programming languages such as AWK, Perl, Tcl, Fortran, Pascal, Icon, Erlang, OCaml, Haskell, MATLAB, R, Ada and programming languages (such as Forth, Basic, Scheme, nesC) that be used in embedded systems can also be easily added in Speare Pro. Add graphical user interface designer in Speare code editor also become relatively easy. Speare code editor was already ready for intellectual property transfer if you are interested in using the source code of it to develop commercial product, please contact us.