Skip to content

Latest commit

 

History

History
130 lines (92 loc) · 3.43 KB

HACKING.rdoc

File metadata and controls

130 lines (92 loc) · 3.43 KB
Raw

Hacking MacRuby ↑

Please read this file if you are considering hacking MacRuby. It provides tips in order to better hack MacRuby and also suggestions on how to submit a patch.

Coding Style ↑

You need to conform to the following coding style in order to get a patch accepted:

  • Indentation starts with 4 space characters, then 1 tabulation (hard), then 1 tabulation (hard) followed by 4 space characters, then 2 tabulations (hard), etc.

    This is the indentation style that was inherited from the original Ruby source code, so we are preserving it.

  • Insert a new line between the type and the name of a function during its definition and start the opening parenthesis on a new line too.

    static void
do_something(void)
{
    ...
}

  • A space must be inserted between keywords and their operand and branches must be written so that an ending parenthesis is always at the end of a line.

    if (some_boolean) {
    ...
}
else {
    ...
}

  • Branches with only one expression must still be covered by parenthesis, even if it’s not mandatory in the C language. Also, do not write one-liner branches.

    if (some_boolean)
    do_something(); /* bad */
if (some_boolean) do_something(); /* bad */

if (some_boolean) {
    /* good */
    do_something();
}

  • A space must be inserted between operators operands.

    int i, x = 40 + 2;
for (i = 0; i < x; i++) {
    ...
}

  • Do not insert a space between a function call and its first parenthesis.

    do_something();

  • A space must be inserted after every argument in a function call.

    do_something(x, y, z);

  • Never pass a non-boolean value as it is to a conditional expression.

    void *ptr = do_something();
if (!ptr) {
    /* bad */
}

if (ptr != NULL) {
    /* good */
}

  • Respect the 80 columns rule when possible. You can violate this rule in case the line contains a long string.

  • In case you need to split multiple conditional expressions into multiple lines, make sure there is a new line before the operator(s).

    if (do_something ||
    do_something2()) {
    /* bad */
    do_something3();
}

if (do_something()
    || do_something2()) {
    /* good */
    do_something3();
}

Debugging ↑

Environment variables ↑

The following environment variables might help you debug easy bugs.

  • GC_DISABLE: set it to any value to disable the GC.

  • GC_DEBUG: set it to any value to enable GC debugging on $stderr.

  • VM_DISABLE_RBO: set it to any value to disable the load of .rbo files.

  • VM_DUMP_IR: set it to any value to dump the LLVM IR on $stderr before the interpreter quits.

  • DYLD_LIBRARY_PATH: in case you are debugging a Cocoa application, set this variable to “.” before starting gdb, and you won’t have to re-install MacRuby every time you re-compile it.

GDB tricks ↑

  • Break on rb_exc_raise to intercept pure Ruby exceptions. You can use a conditional break point in case you only want to break if a specific exception class is being raised: (gdb) b rb_exc_raise Breakpoint 1 at 0x20c49ba5453254: file eval.c, line 312. (gdb) cond 1 *(void **)mesg == rb_eArgError

  • To dump the LLVM IR: (gdb) p RoxorCompiler::shared->module->dump()

  • To print the list of current active blocks: (gdb) p (char *)RoxorVM::current->debug_blocks()

  • To print the list of current active exceptions: (gdb) p (char *)RoxorVM::current->debug_exceptions()