Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 176 lines (122 sloc) 5.163 kB
a2d7abb adding HACKING file (still a work in progress)
Laurent Sansonetti authored
1 == Hacking MacRuby
2
3 Please read this file if you are considering hacking MacRuby. It provides
4 tips in order to better hack MacRuby and also suggestions on how to submit a
5 patch.
6
7 === Coding Style
8
9 You need to conform to the following coding style in order to get a patch
10 accepted:
11
12 * Indentation starts with 4 space characters, then 1 tabulation (hard), then
13 1 tabulation (hard) followed by 4 space characters, then 2 tabulations
14 (hard), etc.
15
16 This is the indentation style that was inherited from the original Ruby source
17 code, so we are preserving it.
18
19 * Insert a new line between the type and the name of a function during its
32bbfa8 @drernie Changed 'parenthesis' to 'brace' in HACKING to match common English m…
drernie authored
20 definition and start the opening brace on a new line too.
a2d7abb adding HACKING file (still a work in progress)
Laurent Sansonetti authored
21
22 static void
23 do_something(void)
24 {
25 ...
26 }
27
28 * A space must be inserted between keywords and their operand and branches must
32bbfa8 @drernie Changed 'parenthesis' to 'brace' in HACKING to match common English m…
drernie authored
29 be written so that an ending brace is always at the end of a line.
a2d7abb adding HACKING file (still a work in progress)
Laurent Sansonetti authored
30
31 if (some_boolean) {
32 ...
33 }
34 else {
35 ...
36 }
37
32bbfa8 @drernie Changed 'parenthesis' to 'brace' in HACKING to match common English m…
drernie authored
38 * Branches with only one expression must still be covered by braces, even
a2d7abb adding HACKING file (still a work in progress)
Laurent Sansonetti authored
39 if it's not mandatory in the C language. Also, do not write one-liner
40 branches.
41
42 if (some_boolean)
43 do_something(); /* bad */
44 if (some_boolean) do_something(); /* bad */
45
46 if (some_boolean) {
47 /* good */
48 do_something();
49 }
50
51 * A space must be inserted between operators operands.
52
53 int i, x = 40 + 2;
54 for (i = 0; i < x; i++) {
55 ...
56 }
57
32bbfa8 @drernie Changed 'parenthesis' to 'brace' in HACKING to match common English m…
drernie authored
58 * Do not insert a space between a function call and its first brace.
a2d7abb adding HACKING file (still a work in progress)
Laurent Sansonetti authored
59
60 do_something();
61
62 * A space must be inserted after every argument in a function call.
63
64 do_something(x, y, z);
65
66 * Never pass a non-boolean value as it is to a conditional expression.
67
68 void *ptr = do_something();
69 if (!ptr) {
70 /* bad */
71 }
72
73 if (ptr != NULL) {
74 /* good */
75 }
76
77 * Respect the 80 columns rule when possible. You can violate this rule in case
78 the line contains a long string.
79
80 * In case you need to split multiple conditional expressions into multiple
81 lines, make sure there is a new line before the operator(s).
82
83 if (do_something ||
84 do_something2()) {
85 /* bad */
86 do_something3();
87 }
88
89 if (do_something()
90 || do_something2()) {
91 /* good */
92 do_something3();
93 }
94
7512f75 added a section about code design
Laurent Sansonetti authored
95 === Code Design
96
97 * Please declare variables as you use them. The whole project is built under the
98 C99 mode so newer constructs are also recommended (such as the definition of
99 iterator variables in 'for' loops).
100
101 * Please use the 'const' qualifier for scalar variables that are not supposed to
102 change.
103
104 * Use 'assert' or 'abort' for situations that should never happen. It is not a
105 problem if you abuse of this, just be clever.
106
107 * Do not use 'alloca' unless you know what you are doing.
108
11e42e2 mention DYLD_LIBRARY_PATH
Laurent Sansonetti authored
109 === Debugging
110
111 ==== Environment variables
a2d7abb adding HACKING file (still a work in progress)
Laurent Sansonetti authored
112
113 The following environment variables might help you debug easy bugs.
114
115 * GC_DISABLE: set it to any value to disable the GC.
116
117 * GC_DEBUG: set it to any value to enable GC debugging on $stderr.
118
3ae269b move the AOT compilation of the stdlib into the main build task, intr…
Laurent Sansonetti authored
119 * VM_DISABLE_RBO: set it to any value to disable the load of .rbo files.
120
e29c2ec now interpreting potential cold paths (work in progress)
Laurent Sansonetti authored
121 * VM_DISABLE_INTERPRETER: set it to any value to disable the use of the
122 builtin interpreter (generally used on cold paths).
123
a2d7abb adding HACKING file (still a work in progress)
Laurent Sansonetti authored
124 * VM_DUMP_IR: set it to any value to dump the LLVM IR on $stderr before the
5e28a91 introduce the VM_STATS environment variable to collect/dump compiler …
Laurent Sansonetti authored
125 program quits.
a2d7abb adding HACKING file (still a work in progress)
Laurent Sansonetti authored
126
aa0e103 mention the new VM_VERIFY_IR environment variable
Laurent Sansonetti authored
127 * VM_VERIFY_IR: set it to any value to force a LLVM module verification before
5e28a91 introduce the VM_STATS environment variable to collect/dump compiler …
Laurent Sansonetti authored
128 the program quits.
129
130 * VM_STATS: set it to any value to collect then print compiler statistics
131 before the program quits.
aa0e103 mention the new VM_VERIFY_IR environment variable
Laurent Sansonetti authored
132
002ed5d now compile some of the VM primitives into bitcode that will be added…
Laurent Sansonetti authored
133 * VM_OPT_LEVEL: set it either to 0, 1, 2 or 3 to change the optimization level
134 of the LLVM code generator.
135
dd534d6 don't instantiate the JIT when running in AOT mode, honor the target …
Laurent Sansonetti authored
136 * VM_KERNEL_PATH: specify a path to a kernel bitcode file to be used instead of
137 the hardcoded one, when deserializing the main module. This is useful when
138 cross-compiling Ruby code to a different architecture.
139
11e42e2 mention DYLD_LIBRARY_PATH
Laurent Sansonetti authored
140 * DYLD_LIBRARY_PATH: in case you are debugging a Cocoa application, set this
141 variable to "." before starting gdb, and you won't have to re-install MacRuby
142 every time you re-compile it.
143
f966153 adding some tips about the thread local collector
Laurent Sansonetti authored
144 * AUTO_USE_TLC: set this variable to 0 to disable the thread local collector.
145
11e42e2 mention DYLD_LIBRARY_PATH
Laurent Sansonetti authored
146 ==== GDB tricks
a2d7abb adding HACKING file (still a work in progress)
Laurent Sansonetti authored
147
b4b975c adding a tip
Laurent Sansonetti authored
148 * Break on rb_exc_raise to intercept pure Ruby exceptions. You can use a
149 conditional break point in case you only want to break if a specific
150 exception class is being raised:
151 (gdb) b rb_exc_raise
152 Breakpoint 1 at 0x20c49ba5453254: file eval.c, line 312.
153 (gdb) cond 1 *(void **)mesg == rb_eArgError
f18ae63 more gdb tips
Laurent Sansonetti authored
154
155 * To dump the LLVM IR:
156 (gdb) p RoxorCompiler::shared->module->dump()
157
158 * To print the list of current active blocks:
159 (gdb) p (char *)RoxorVM::current->debug_blocks()
160
161 * To print the list of current active exceptions:
162 (gdb) p (char *)RoxorVM::current->debug_exceptions()
f966153 adding some tips about the thread local collector
Laurent Sansonetti authored
163
164 * To determine if a given object is thread-local:
d1685ab mention rb_symbolicate
Laurent Sansonetti authored
165 (gdb) p (int)gdb_is_local(<address>)
166
167 * To symbolize a Ruby address (named as ??) in the backtrace:
168 (gdb) p (void)rb_symbolicate(<address>)
d5a774d add rb_print_memory_objects() debug function
Laurent Sansonetti authored
169
170 * To print the addresses of all memory objects of a given minimum size (useful
171 when debugging memory leaks):
172 (gdb) p (void)rb_print_memory_objects(<size>)
173
174 * To print the GC references of a given memory object:
175 (gdb) info gc-references <address>
Something went wrong with that request. Please try again.