Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 144 lines (109 sloc) 6.18 kb
547f4a3 Cleaned up a bunch of files, added a codestyle validator and some inform...
cjdelisle authored
1 Patches are very much welcome!
2 ==============================
3
bcdee99 @mcinglis Fix line lengths in README and HACKING
mcinglis authored
4 If you want to get a change included in cjdns, the best thing to do is start by
5 asking in IRC if the change fits the spirit of the project, then developing
6 your change in your own git tree and then asking for it to be merged in with
7 the others.
547f4a3 Cleaned up a bunch of files, added a codestyle validator and some inform...
cjdelisle authored
8
bcdee99 @mcinglis Fix line lengths in README and HACKING
mcinglis authored
9 Small patches are easy to include and large ones are hard to validate. Consider
10 breaking your evil plans up into a bunch of nice little changes which are easy
11 to understand and prove safe.
547f4a3 Cleaned up a bunch of files, added a codestyle validator and some inform...
cjdelisle authored
12
13
14 Codestyle:
15 ----------
16
17 * Indentation: 4 spaces, tabs are not in the codebase.
bcdee99 @mcinglis Fix line lengths in README and HACKING
mcinglis authored
18 * Trailing whitespace is not in the codebase, Windows users make sure you have
19 git configured to remove carrage return characters as lines in the codebase
20 are \n deliniated.
547f4a3 Cleaned up a bunch of files, added a codestyle validator and some inform...
cjdelisle authored
21 * File names and structures are CamelCase with first letter capital.
bcdee99 @mcinglis Fix line lengths in README and HACKING
mcinglis authored
22 * All globally visible functions shall begin with the name of the file in which
23 they are defined followed by an underscore and then the name of the function.
24 AKA `ThingThatDoesStuff_doStuff()`
25 * Functions and local variables shall use camelCase names with first letter
26 lowercase.
27 * Structures declared in header files must begin with, or be, the name of the
28 header in which they are declared.
29 * Global variables as well as static local variables are forbidden. Constants
30 are acceptable.
31 * All preprocessor definitions in header files must contain the name of the
32 header file followed by an underscore and the definition name in all capitals
33 AKA `define SillyMath_VALUE_OF_PI 3` or `#define SillyMath_DIVIDE(a,b) (a /
34 b)` it is sometimes acceptable for macros to use camel case as is done in
35 Endian.h, use judgement.
36
37 If there is a better way, come to irc and announce it, this code style has
38 evolved to where it is now.
547f4a3 Cleaned up a bunch of files, added a codestyle validator and some inform...
cjdelisle authored
39
bdec61d Documented Assert.h
Caleb James DeLisle authored
40 Assert.h
41 --------
42
43 Lining your code with assertions is great! You'll find a few macros in Assert.h
44 to help you. If an assertion is cheap or in a cold codepath or you otherwise feel
45 it's important that it's never skipped, use `Assert_true()`, if you want the
46 asserion to be skipped on small hardware where `-DPARANOIA` is disabled, use
47 `Assert_ifParanoid()`, if your assertion might be triggered by "bad nodes" in a
48 realistic network and is for simulation only, use `Assert_ifTesting()` and it
49 will only be included if `-DTESTING` is passed. If your assertion has
50 side-effects, you must use `Assert_true()` because these are macros which
51 are completely removed if they are disabled.
547f4a3 Cleaned up a bunch of files, added a codestyle validator and some inform...
cjdelisle authored
52
53
54 Testing
55 -------
56
bcdee99 @mcinglis Fix line lengths in README and HACKING
mcinglis authored
57 Any file in a /test/ subdirectory which ends with `_test.c` will be compiled as
019ee51 updated hacking with lots of new documentation
Caleb James DeLisle authored
58 a test and added to the testing regime through some nodejs hackery. you might
59 Tests can fail by returning non-zero or using Assert_true() statements, whatever
60 makes sense.
547f4a3 Cleaned up a bunch of files, added a codestyle validator and some inform...
cjdelisle authored
61
f16d330 Update HACKING.md
Caleb James DeLisle authored
62 *All patches which add tests will be addressed before any patches which don't.*
81344bc Document how to profile cjdns
Caleb James DeLisle authored
63
64
019ee51 updated hacking with lots of new documentation
Caleb James DeLisle authored
65 Debugging
66 ---------
67
68 sudo gdb ./cjdroute -ex 'set follow-fork-mode child' -ex 'r < /etc/cjdroute.conf'
69
70 If it crashes, type `backtrace` to get some useful information.
71 The backtrace will show where in the program it crashed and where called that
72 and where called that, etc. Down the left side of the screen are numbers next
73 to the function names, you can select one of these for further inspection using
74 the `select-frame` command. Once you've selected a frame you can print arguments
75 to the function or local variables (maybe not if compiler optimization was
76 enabled!). The `print` command will help you extract the value of a local variable,
77 an argument to the function or really anything. In gdb, tab complete works for both
78 commands and variables/arguments so if in doubt, hit tab :)
79
f019cf2 Few more little notes
Caleb James DeLisle authored
80 To stop the program in the debugger, use ctrl+c, this will put you in the debugger shell.
81
82 Once in the debugger shell, to quit the debugger use ctrl+d, if the program is
83 running it will prompt you, another ctrl+d will be taken as a "yes, please quit".
84
019ee51 updated hacking with lots of new documentation
Caleb James DeLisle authored
85
81344bc Document how to profile cjdns
Caleb James DeLisle authored
86 Profiling
87 ---------
88
89 The best way to profile cjdns is using Brendan Gregg's FlameGraph generator.
90 http://www.brendangregg.com/FlameGraphs/cpuflamegraphs.html
91 You can do this on Linux using the `perf` utility.
92
93 sudo perf record -a -g -F 997 -p `pidof cjdroute`
94 # let this run for a while, put cjdroute through some exercises
95 <ctrl+c>
96 sudo perf script | ../FlameGraph/stackcollapse-perf.pl > ./cjdns-stackcollapse.out
97 ../FlameGraph/flamegraph.pl < ./cjdns-stackcollapse.out > ./cjdns-stackcollapse.svg
98 chromium ./cjdns-stackcollapse.svg
019ee51 updated hacking with lots of new documentation
Caleb James DeLisle authored
99
100
101 Simulating
102 ----------
103
104 Cjdns comes with it's own simulator, it will create *n* nodes and link them together
105 however you wish. It's like having many cjdns processes all running together but they're
106 all in the same process so it is much more efficient. You can set admin credentials on
107 one node and then use the admin tools to access it as you would an ordinary router.
108 You will however need private keys whose public keys hash to ip addresses beginning with
109 fc. To make these keys, use the `makekeys` utility.
110
111 ./makekeys | head -n 32 > keys.txt
112
113 To convert the list of keys into a simulator configuration, use `makesim.js`, note there
114 are interesting constants inside of `makesim.js` which you might want to alter.
115
116 node ./contrib/nodejs/makesim.js keys.txt > ~/my-cjdns-simulation.json
117
118 Once you have a simultaion setup, you may want to add your admin credentials to one of
119 the nodes so you can inspect it, dump the table, etc...
120
121 Example simulation config entry with added admin block:
122
123 "fc5c:0537:606a:3d7e:c9f0:2103:4dcd:6bc8": {
124 "privateKey": "0dc3d33bbffc2d16c175df463110c6d164714a40d23db2f83539664b7365a5b6",
125 "peers": [
126 "fc1c:84bf:9557:1ce4:4862:fd82:5105:9984",
127 "fc1c:90e4:2953:938b:47cc:65c3:6540:dff6",
128 "fc1b:7ea7:911f:f2d5:7685:ac22:6c4f:8b15"
129 ],
130 "admin":
131 {
132 "bind": "127.0.0.1:11234",
133 "password": "the_password_you_will_use_to_connect"
134 }
135 },
136
f019cf2 Few more little notes
Caleb James DeLisle authored
137 And to start it up (in the debugger):
138
139 gdb sybilsim -ex 'r < ~/my-cjdns-simulation.json'
140
019ee51 updated hacking with lots of new documentation
Caleb James DeLisle authored
141 BUG: Sometimes the simulator doesn't really start up correctly! If you could figure out
f019cf2 Few more little notes
Caleb James DeLisle authored
142 what is going wrong, your help would be most appreciated, if not, you can just quit and
143 then restart it again and it should start up ok.
Something went wrong with that request. Please try again.