Status: | Merged |
---|---|
Approved by: | Paweł Forysiuk |
Approved revision: | 6179 |
Merged at revision: | 6201 |
Proposed branch: | lp:~kalikiana/midori/hacking |
Merge into: | lp:midori |
Diff against target: |
475 lines (+203/-251) 3 files modified
HACKING (+200/-169) INSTALL (+0/-82) tools/release (+3/-0) |
To merge this branch: | bzr merge lp:~kalikiana/midori/hacking |
Related bugs: |
Reviewer | Review Type | Date Requested | Status |
---|---|---|---|
Paweł Forysiuk | Approve | ||
Review via email:
|
Commit message
Replace INSTALL/ HACKING with exported Contribute wiki page
Description of the change
Replace INSTALL/ HACKING with exported Contribute wiki page
To post a comment you must log in.
Revision history for this message
![](/+icing/build/overlay/assets/skins/sam/images/close.gif)
Paweł Forysiuk (tuxator) wrote : | # |
Revision history for this message
![](/+icing/build/overlay/assets/skins/sam/images/close.gif)
Cris Dywan (kalikiana) wrote : | # |
Both MIDORI_TOUCHSCREEN and MIDORI_
Revision history for this message
![](/+icing/build/overlay/assets/skins/sam/images/close.gif)
Cris Dywan (kalikiana) wrote : | # |
I will add something about G_DEBUG=all to the wiki, we can polish that until release and the file will be updated as the script is run.
Revision history for this message
![](/+icing/build/overlay/assets/skins/sam/images/close.gif)
Paweł Forysiuk (tuxator) : | # |
review:
Approve
Preview Diff
[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1 | === modified file 'HACKING' |
2 | --- HACKING 2011-01-30 20:35:39 +0000 |
3 | +++ HACKING 2013-05-29 19:40:32 +0000 |
4 | @@ -1,169 +1,200 @@ |
5 | -This file is licensed under the terms of the expat license, see the file EXPAT. |
6 | - |
7 | -+ Hacking guide for Midori + |
8 | - |
9 | -- How to contribute |
10 | -- Coding style |
11 | -- Source files in the project |
12 | -- Examplary source code |
13 | - |
14 | -+++ How to contribute +++ |
15 | - |
16 | -There are several ways to contribute to the project: |
17 | - |
18 | -For translating, have a look at the file TRANSLATE. |
19 | - |
20 | -For helping with testing and triaging bug reports, you should register with the bug tracker at https://bugs.launchpad.net/midori and join #midori on irc.freenode.net where a lot of problems are discussed. You can start right away by trying to reproduce bug reports and comment with your findings. |
21 | - |
22 | -If you are interested in contributing code, there are a few options. You can join #midori to discuss a particular problem you would like to look into, or a feature you would want to implement. Opening a bug report or feature request if there isn't already one is the next step. To attract some attention, if you attached a patch or have questions, ask in #midori. |
23 | - |
24 | -+++ Coding style +++ |
25 | - |
26 | -Indentation is 4 spaces, no tabs, preferrably at 80 to 120 columns per line to |
27 | -avoid automated line-breaks. Trailing whitespace is not desirable. |
28 | - |
29 | -Declarations go to the beginning of a block, not inline. Variables of one plain |
30 | -type may be grouped in one declaration, pointer types may not be grouped. The |
31 | -asterisk goes next to the type. |
32 | -Variables should be ordered in the order they are used. |
33 | - |
34 | -Comments explain functionality, they should not state facts. The appropriate |
35 | -style is always C style /* */, not C++ style. |
36 | - |
37 | -Variable and function names should be animal, animal_shelter or animalsc in |
38 | -case it would otherwise be very long. Loop counters may be single letters. |
39 | -Type names should be Animal, AnimalShelter or AnimalSC. No prefixes from third |
40 | -party projects should be used, such as GTK or WebKit, while underlines may be |
41 | -used but do not have a particular meaning. |
42 | - |
43 | -There is a space between functions or keywords and round brackets, and curly |
44 | -brackets always go on separate lines, at the indentation level of the |
45 | -function, conditional or loop expression. Curly brackets are left out for single |
46 | -statement conditionals and loops unless they notably help readability. |
47 | -The type of a function goes on a separate line before the function. |
48 | -Preprocessor instructions are indented with the code they relate to. |
49 | - |
50 | -Code history is precious, so one should avoid renaming a lot of functions at |
51 | -once or moving whole paragraphs only to add or remove a level of indentation. |
52 | -Moving blocks of code around is also undesriable because it makes patches less |
53 | -readable since the result looks like new code. |
54 | - |
55 | - |
56 | -+++ Source files in the project +++ |
57 | - |
58 | -Core: |
59 | - Files prefixed with "midori-" in the folder "midori" make up the core. They |
60 | - are essential to running the browser and mostly tailored to the browser. |
61 | - All header files prefixed with "midori-" are considered supported API and |
62 | - can be used to implement extensions. |
63 | - "sokoke" is a collection of very specialized helper functions which change |
64 | - from time to time as needed. In the past some of the code was moved to |
65 | - "katze" when it was considered generally useful. |
66 | - "socket" is a socket implementation with no dependency on other parts of |
67 | - the core, which is used if Midori is built without an external single |
68 | - instance support library. |
69 | -Panels: |
70 | - Files in the "panels" folder are classes that implement MidoriViewable and |
71 | - which are loaded into the MidoriPanel at startup. These panels are in |
72 | - principle optional. |
73 | -Katze: |
74 | - Re-usable classes and utility functions that don't depend on the core and |
75 | - some of that code indeed found its way into other projects. |
76 | -Extensions: |
77 | - These are extensions, written in C, which are loaded optionally if the user |
78 | - so chooses. Extensions can use API from "midori-" and "katze-" headers. Each |
79 | - module consists of either a single .c file or a folder with .c files. |
80 | -Tests: |
81 | - Unit tests are run regularly to verify possible regressions or measure |
82 | - performance of implementations. Except for select cases code changes should |
83 | - not cause failure of unit tests. |
84 | - |
85 | - |
86 | -+++ Examplary source code +++ |
87 | - |
88 | - /* |
89 | - Copyright |
90 | - LICENSE TEXT |
91 | - */ |
92 | - |
93 | - #include "foo.h" |
94 | - |
95 | - #include "bar.h" |
96 | - |
97 | - #include <glib.h> |
98 | - |
99 | - void |
100 | - foobar (FooEnum bar, const gchar* foo) |
101 | - { |
102 | - gint n, i; |
103 | - |
104 | - if (!foo) |
105 | - return; |
106 | - |
107 | - #ifdef BAR_STRICT |
108 | - if (bar == FOO_N) |
109 | - { |
110 | - g_print ("illegal value for 'bar'.\n"); |
111 | - return; |
112 | - } |
113 | - #endif |
114 | - |
115 | - /* this is an example */ |
116 | - switch (bar) |
117 | - { |
118 | - case FOO_FOO: |
119 | - n = bar + 1; |
120 | - break; |
121 | - case FOO_BAR: |
122 | - n = bar + 10; |
123 | - break; |
124 | - default: |
125 | - n = 1; |
126 | - } |
127 | - |
128 | - for (i = 0; i < n; i++) |
129 | - { |
130 | - g_print ("%s\n", foo); |
131 | - } |
132 | - } |
133 | - |
134 | -Header file example: |
135 | - |
136 | - /* |
137 | - Copyright |
138 | - LICENSE TEXT |
139 | - */ |
140 | - |
141 | - #ifndef __FOO_H__ |
142 | - #define __FOO_H__ 1 |
143 | - |
144 | - #ifdef HAVE_BAR_H |
145 | - #define BAR_STRICT |
146 | - #endif |
147 | - |
148 | - /* Types */ |
149 | - |
150 | - typedef enum |
151 | - { |
152 | - FOO_FOO, |
153 | - FOO_BAR, |
154 | - FOO_N |
155 | - } FooEnum; |
156 | - |
157 | - typedef struct |
158 | - { |
159 | - FooEnum foo_bar; |
160 | - } FooStruct; |
161 | - |
162 | - /* Declarations */ |
163 | - |
164 | - void |
165 | - foo_bar (FooEnum bar, |
166 | - const gchar* foo); |
167 | - |
168 | - const gchar* |
169 | - foo_foo (FooStruct foo_struct, |
170 | - guint number, |
171 | - gboolean flag); |
172 | - |
173 | - #endif /* !__FOO_H__ */ |
174 | +====== Midori - Contribute ====== |
175 | + |
176 | +**This document is licensed under the LGPL 2.1.** |
177 | + |
178 | +====== Check out the sources ====== |
179 | + |
180 | +bzr branch lp:midori |
181 | + |
182 | +The development **trunk** (master, tip) is the latest iteration of the next release. Browse it online and look for other branches at http://code.launchpad.net/midori or http://bazaar.launchpad.net/~midori/midori/trunk/tarball download a tarball of the latest revision. |
183 | + |
184 | +//The code used to be hosted in git.xfce.org/apps/midori.// |
185 | +====== Join IRC chat rooms ====== |
186 | + |
187 | +Join irc://irc.freenode.net/midori #midori on Freenode https://kiwiirc.com/client/irc.freenode.net/midori or use webchat to talk about Midori, discuss bugs and new ideas. |
188 | +====== Contribute other than touching code ====== |
189 | + |
190 | + * http://bugs.launchpad.net/midori Go through problem reports and check Unconfirmed bugs or those lacking information and mark any duplicates you spot |
191 | + * https://www.bountysource.com/#trackers/130181-midori Add a bounty for a feature or bug you'd like to support |
192 | + |
193 | +====== Build the code ====== |
194 | + |
195 | +./waf configure --prefix=/usr |
196 | +./waf build |
197 | +sudo ./waf install |
198 | + |
199 | +Midori can be **run without being installed**. |
200 | + |
201 | +_build/default/midori/midori |
202 | + |
203 | +You can use a **temporary folder for testing** without affecting normal settings |
204 | + |
205 | +_build/default/midori/midori -c /tmp/midoridev |
206 | + |
207 | +You'll want to **unit test** the code if you're testing a new version or contributed your own changes: |
208 | + |
209 | +xvfb-run ./waf check |
210 | + |
211 | +Automated daily builds in Launchpad (https://launchpad.net/~elementary-os/+archive/daily ppa:elementary-os/daily and https://launchpad.net/~midori/+archive/midori-dev ppa:midori/midori-dev) run these tests as well. |
212 | +====== Debugging issues ====== |
213 | + |
214 | +Testing an installed release may reveal crashers or memory corruption which require investigating from a local build and obtaining a stacktrace (backtrace, crash log). |
215 | + |
216 | +_build/default/midori/midori -g [OPTIONAL ARGUMENTS] |
217 | + |
218 | +For more specific debugging output, depending on the feature in question you may use |
219 | + |
220 | +env MIDORI_DEBUG=help _build/default/midori/midori |
221 | + |
222 | +====== Coding style and quality ====== |
223 | + |
224 | +Midori code should in general have: |
225 | + |
226 | + * 4 space indentation, no tabs |
227 | + * Between 80 to 120 columns |
228 | + * Prefer /* */ style comments |
229 | + * Call variables //animal// and //animal_shelter// instead of <del>camelCase</del> |
230 | + * Keep a space between functions/ keywords and round parentheses |
231 | + |
232 | +For Vala: |
233 | + |
234 | + * Prefer //new Gtk.Widget ()// over //using Gtk; new Widget ()// |
235 | + * Stick to standard Vala-style curly parentheses on the same line |
236 | + * Cuddled //} else {// and //} catch (Error error) {// |
237 | + |
238 | +For C: |
239 | + |
240 | + * Always keep { and } on their own line |
241 | + |
242 | +//Extensions may historically diverge from the standard styling on a case-by-case basis// |
243 | + |
244 | +====== Committing code ====== |
245 | + |
246 | +Tell Bazaar your name if you haven't yet |
247 | + bzr whoami "Real Name <email@address>" |
248 | + |
249 | +See what you did so far |
250 | + bzr diff |
251 | + |
252 | +Get an overview of changed and new files |
253 | + bzr status |
254 | + |
255 | +Add new files, move/ rename or delete |
256 | + bzr add FILENAME |
257 | + bzr mv OLDFILE NEWFILE |
258 | + bzr rm FILENAME |
259 | + |
260 | +Commit all current changes - Bazaar automatically picks up edited files. //If you're used to git, think of an implicit staging area.// |
261 | + bzr commit -p |
262 | + |
263 | +If you've done several commits |
264 | + bzr log | less |
265 | + bzr log -p | less |
266 | + |
267 | +In the case you committed something wrong or want to ammend it: |
268 | + bzr uncommit |
269 | + |
270 | +If you end up with unrelated debugging code or other patches in the current changes, it's sometimes handy to temporarily clean up. //This may be seen as bzr's version of git stash.// |
271 | + bzr shelve |
272 | + bzr commit -p |
273 | + bzr unshelve |
274 | + |
275 | +Remember to keep your branch updated: |
276 | + bzr pull |
277 | + |
278 | +As a general rule of thumb, ''bzr help COMMAND'' gives you an explanation of any command and ''bzr help commands'' lists all available commands. |
279 | + |
280 | +//If you're a die-hard git user, http://zyga.github.io/git-lp/ checkout git-lp to use git commands with the Bazaar repository.// |
281 | + |
282 | +====== Push proposed changes ====== |
283 | + |
284 | +If you haven't yet, https://launchpad.net/~/+editsshkeys check that Launchpad has your SSH key - you can create an SSH key with **Passwords and Keys** aka **Seahorse** or ''ssh-keygen -t rsa'' - and use ''bzr launchpad-login'' to make youself known to bzr locally. |
285 | + |
286 | +If you checked out trunk, and added your patch(es), just **push it under your username** in Launchpad and you can **propose it for merging into trunk**. This will automatically request a **review from other developers** who can then comment on it and provide feedback. |
287 | + |
288 | +bzr push --remember lp:~USERNAME/midori/fix-bug1120383 && bzr lp-propose-merge lp:midori |
289 | + |
290 | +lp-propose-merge command may not be working on some distributions like Arch or Fedora. |
291 | +In case you get error like //bzr: ERROR: Unable to import library "launchpadlib": No module named launchpadlib// just use Launchpad's Web UI to propose a merge. |
292 | + |
293 | + |
294 | +**What happens to all the branches?** |
295 | + |
296 | +Leave the branches alone, **approved branches are cleared automatically** by Launchpad. |
297 | + |
298 | +For larger feature branches, **use the team** in Launchpad to allow other developers to work on the code with you. |
299 | + |
300 | +bzr push --remember lp:~midori/midori/featuritis && bzr lp-propose-merge lp:midori |
301 | + |
302 | +What if I want to help out on an **existing merge request** that I can't push to? |
303 | + |
304 | + |
305 | +bzr branch ~OTHERPERSON/midori/fix-bug1120383 |
306 | +cd fix-bug1120383 |
307 | +# make commits |
308 | +bzr push lp:USERNAME~/midori/fix-bug1120383 |
309 | +bzr lp-propose-merge ~OTHERPERSON/midori/fix-bug1120383 |
310 | + |
311 | + |
312 | +Updating a branch that may be out of sync with trunk: |
313 | + |
314 | + |
315 | +bzr pull |
316 | +bzr: ERROR: These branches have diverged |
317 | +bzr merge lp:midori |
318 | +# Hand-edit conflicting changes |
319 | +bzr resolve FILENAME |
320 | +# If any conflicts remain continue fixing |
321 | +bzr commit -m 'Merge lp:midori' |
322 | + |
323 | + |
324 | +Save a little bandwidth, **branch from an existing local copy** that you keep around: |
325 | + |
326 | + |
327 | +bzr branch lp:midori midori |
328 | +bzr branch midori midori.fix-bug1120383 |
329 | +cd midori.fix-bug1120383 |
330 | +bzr pull lp:midori |
331 | + |
332 | +====== Midori for Windows ====== |
333 | +===== Dependencies ===== |
334 | +Midori for Windows is compiled on a Linux host and MinGW stack. For the current build Fedora 18 packages are used. Packages needed are listed below: |
335 | + |
336 | +yum install gcc vala intltool |
337 | + |
338 | +For a native build |
339 | +yum install libsoup-devel webkitgtk3-devel sqlite-devel |
340 | + |
341 | +For cross-compilation |
342 | +yum install mingw{32,64}-webkitgtk3 mingw{32,64}-glib-networking mingw{32,64}-gdb |
343 | + |
344 | +Packages needed when assembling the archive |
345 | + yum install faenza-icon-theme p7zip mingw32-nsis |
346 | + |
347 | +Installing those should get you the packages needed to successfully build and develop Midori for Win32. |
348 | + |
349 | +===== Building ===== |
350 | +For 32-bit builds: |
351 | + |
352 | +mingw32-env |
353 | +./configure --enable-gtk3 --prefix=/usr/i686-w64-mingw32/sys-root/mingw/ |
354 | +make |
355 | +sudo make install |
356 | + |
357 | +For 64-bit builds: |
358 | + |
359 | +mingw64-env |
360 | +./configure --enable-gtk3 --prefix=/usr/x86_64-w64-mingw32/sys-root/mingw/ |
361 | +make |
362 | +sudo make install |
363 | + |
364 | +Once built and tested you can assemble the Midori archive with a helper script |
365 | +32-bit build: |
366 | +env MINGW_PREFIX="/usr/i686-w64-mingw32/sys-root/mingw" ./win32/makedist/makedist.midori |
367 | +64-bit build: |
368 | +env MINGW_PREFIX="/usr/x86_64-w64-mingw32/sys-root/mingw/" ./win32/makedist/makedist.midori x64 |
369 | + |
370 | +===== Testing ===== |
371 | +For testing your changes unfortuantely a real system is needed because Midori and WebKitGTK+ don't work properly under Wine. Even if it works some problems are not visible when using Wine, but are present when running under a real Windows system and vice versa. |
372 | + |
373 | +One way around it is to virtualize Windows on a Linux host and mount your MinGW directories as a network drive or shared folder. |
374 | \ No newline at end of file |
375 | |
376 | === removed file 'INSTALL' |
377 | --- INSTALL 2012-11-26 18:05:35 +0000 |
378 | +++ INSTALL 1970-01-01 00:00:00 +0000 |
379 | @@ -1,82 +0,0 @@ |
380 | -This file is licensed under the terms of the expat license, see the file EXPAT. |
381 | - |
382 | -+++ Installing Midori +++ |
383 | - |
384 | -Building and installing Midori is straightforward. |
385 | - |
386 | -Make sure you have Python 2.4 or higher installed. |
387 | - |
388 | -Change to the Midori folder on your hard disk in a terminal. |
389 | - |
390 | -Run './waf configure' |
391 | - |
392 | -Run './waf build' |
393 | - |
394 | -You can now run Midori from the build folder like so |
395 | - |
396 | -'_build/default/midori/midori' |
397 | - |
398 | -Midori will pick up extensions and resources from the build folder; |
399 | -it will NOT use localizations. |
400 | - |
401 | -You can install it with './waf install' |
402 | - |
403 | -If you need to do a clean rebuild, you can do either './waf clean' |
404 | -in order to remove binaries or './waf distclean' which deletes generated |
405 | -configuration files as well. |
406 | - |
407 | -For further options run './waf --help' |
408 | - |
409 | -+++ Debugging Midori +++ |
410 | - |
411 | -Midori is by default built with debugging symbols, make sure you have |
412 | -installed 'gdb', the GNU Debugger. |
413 | - |
414 | -It's a good idea to execute all unit test cases and see that they pass. |
415 | - |
416 | -'xvfb-run ./waf check' |
417 | - |
418 | -In this example, Xvfb is used to avoid relying on the local user setup. |
419 | - |
420 | -You can also run Midori proper as 'gdb _build/default/midori/midori'. |
421 | - |
422 | -Inside gdb, type 'run'. |
423 | - |
424 | -Try to reproduce a crash that you experienced earlier, |
425 | -this time Midori will freeze at the point of the crash. |
426 | -Switch to your terminal, type bt ('backtrace') and hit Return. |
427 | -What you obtained now is a backtrace that should include |
428 | -function names and line numbers. |
429 | - |
430 | -If the problem is a warning and not a crash, try this: |
431 | - |
432 | -'G_DEBUG=all gdb _build/default/midori/midori' |
433 | - |
434 | -If you are interested in HTTP communication, try this: |
435 | - |
436 | -'MIDORI_DEBUG=headers _build/default/midori/midori' |
437 | - |
438 | -Where 'headers' can be replaced with 'body' to get full message contents. |
439 | - |
440 | -If you are interested in (non-) touchscreen behaviour, try this: |
441 | - |
442 | -'MIDORI_TOUCHSCREEN=1 _build/default/midori/midori', or |
443 | - |
444 | -'MIDORI_TOUCHSCREEN=0 _build/default/midori/midori' |
445 | - |
446 | -If you want to "dry run" without WebKitGTK+ rendering, try this: |
447 | - |
448 | -'MIDORI_DEBUG=unarmed _build/default/midori/midori' |
449 | - |
450 | -If you want to test bookmarks, you can enable database tracing: |
451 | - |
452 | -'MIDORI_DEBUG=bookmarks _build/default/midori/midori' |
453 | - |
454 | -To disable Netscape plugins, use MOZ_PLUGIN_PATH=/. |
455 | - |
456 | -When running from the build folder, extensions will also be located |
457 | -in the build folder (setting MIDORI_EXTENSION_PATH is no longer needed). |
458 | - |
459 | -For further information a tutorial for gdb and |
460 | -reading up on how you can install debugging |
461 | -symbols for libraries used by Midori are recommended. |
462 | |
463 | === modified file 'tools/release' |
464 | --- tools/release 2013-05-19 14:04:16 +0000 |
465 | +++ tools/release 2013-05-29 19:40:32 +0000 |
466 | @@ -16,6 +16,9 @@ |
467 | OLDVER=0.5.1 |
468 | sed -i "s@$OLDVER@$NEWVER@g" wscript win32/makedist/midori.nsi |
469 | echo; echo v$NEWVER:; bzr log --line -rtag:$OLDVER.. | sed -r 's@.+2013-[0-9]+-[0-9]+ @@' | grep -v l10n | grep -v makedist | grep -v tools/release | grep -v nsi | grep -v -E 'Update .+ translation'; echo |
470 | + curl http://wiki.xfce.org/_export/raw/midori/contribute | \ |
471 | + sed -r 's@\[\[([^|]+)\|([^]]+)\]\]@\1 \2@g' | \ |
472 | + sed -r 's@<code( bash|)>|</code>@@g' > HACKING |
473 | curl http://wiki.xfce.org/_export/xhtml/midori/faq | \ |
474 | sed 's@This is a list of frequently asked questions@This is <a href="http://wiki.xfce.org/midori/faq">a snapshot of the online FAQ</a>@g' | \ |
475 | sed 's@<link rel="style.*>@<link rel="stylesheet" href="faq.css" />@g' > data/faq.html |
Would be awesome if we could strip markup somehow. Mostly <code></code> tags and [[ ]] for links.
I guess italics tag // will be tricky to match. But those two above should go as they go in the way when trying to read the text.
There is no info now about EXTENSION_ PATH
MIDORI_TOUCHSCREEN MIDORI_
and G_DEBUG=all
Probably could/should be added to wiki then.
Otherwise looks good.