Xfce Wiki

Sub domains
 
no way to compare when less than two revisions

Differences

This shows you the differences between two versions of the page.


Previous revision
Next revision
—midori:contribute [2013/10/12 23:05] – [Midori with(out) Granite] kalikiana
Line 1: Line 1:
 +====== Midori - Contribute ======
  
 +**This document is licensed under the LGPL 2.1.**
 +
 +====== Check out the sources ======
 +
 +<code bash>bzr branch lp:midori</code>
 +
 +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]].
 +
 +//The code used to be hosted in git.xfce.org/apps/midori.//
 +
 +Keep your copy updated:
 +
 +<code bash>bzr merge --pull</code>
 +====== Join IRC chat rooms ======
 +
 +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.
 +====== Contribute other than touching code ======
 +
 +  * [[http://bugs.launchpad.net/midori|Go through problem reports]] and check Unconfirmed bugs or those lacking information and mark any duplicates you spot
 +  * [[https://www.bountysource.com/#trackers/130181-midori|Add a bounty]] for a feature or bug you'd like to support
 +  * [[https://translations.launchpad.net/midori/trunk/+pots/trunk|Translate to your own language]]
 +  * [[https://github.com/eustasy/midori-browser.org/issues|Report website bugs]]
 +  * Write [[tutorial|your own extension]] - granted that's code, too, but maybe a little easier than hacking the core.
 +====== Build the code ======
 +
 +<code bash>mkdir _build
 +cd _build
 +cmake -DCMAKE_INSTALL_PREFIX=/usr ..
 +make
 +sudo make install</code>
 +
 +//Advanced Tip: Pass "-G Ninja" to cmake to use [[http://martine.github.io/ninja/|Ninja]] instead of make (usually packaged as ninja or ninja-build).//
 +
 +If using GTK+3 you'll want to add <code bash>-DUSE_GTK3</code> to the cmake command line.
 +
 +Midori can be **run without being installed**.
 +
 +<code bash>_build/midori/midori</code>
 +
 +You can use a **temporary folder for testing** without affecting normal settings
 +
 +<code bash>_build/midori/midori -c /tmp/midoridev</code>
 +
 +You'll want to **unit test** the code if you're testing a new version or contributed your own changes:
 +
 +<code bash>xvfb-run make check</code>
 +
 +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.
 +====== Debugging issues ======
 +
 +Testing an installed release may reveal crashers or memory corruption which require investigating from a local build and obtaining a stacktrace (backtrace, crash log).
 +
 +<code bash>_build/midori/midori -g [OPTIONAL ARGUMENTS]</code>
 +
 +If the problem is a warning, not a crash GLib has a handy feature
 +
 +<code bash>env G_DEBUG=all _build/midori/midori -g</code>
 +
 +For more specific debugging output, depending on the feature in question you may use
 +
 +<code bash>env MIDORI_DEBUG=help _build/midori/midori</code>
 +
 +To verify a regression you might need to revert a particular change:
 +
 +<code bash>
 +# Revert only r6304
 +bzr merge . -r 6304..6303
 +</code>
 +====== Coding style and quality ======
 +
 +Midori code should in general have:
 +
 +  * 4 space indentation, no tabs
 +  * Between 80 to 120 columns
 +  * Prefer /* */ style comments
 +  * Call variables //animal// and //animal_shelter// instead of <del>camelCase</del>
 +  * Keep a space between functions/ keywords and round parentheses
 +
 +For Vala:
 +
 +  * Prefer //new Gtk.Widget ()// over //using Gtk; new Widget ()//
 +  * Stick to standard Vala-style curly parentheses on the same line
 +  * Cuddled //} else {// and //} catch (Error error) {//
 +
 +For C:
 +
 +  * Always keep { and } on their own line
 +
 +//Extensions may historically diverge from the standard styling on a case-by-case basis//
 +
 +====== Committing code ======
 +
 +Tell Bazaar your name if you haven't yet
 +    bzr whoami "Real Name <email@address>"
 +
 +See what you did so far
 +    bzr diff
 +
 +Get an overview of changed and new files
 +    bzr status
 +
 +Add new files, move/ rename or delete
 +    bzr add FILENAME
 +    bzr mv OLDFILE NEWFILE
 +    bzr rm FILENAME
 +
 +Commit all current changes - Bazaar automatically picks up edited files. //If you're used to git, think of an implicit staging area.//
 +    bzr commit -p
 +
 +If you have one or more related bug reports you should pass them as arguments. Once these commits are merged the bug will automatically be closed and the commit log shows clickable links to the reports.
 +    bzr commit -p --fixes=lp:1111999
 +
 +If you've done several commits
 +    bzr log | less
 +    bzr log -p | less
 +
 +In the case you committed something wrong or want to ammend it:
 +    bzr uncommit
 +
 +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.//
 +    bzr shelve
 +    bzr commit -p
 +    bzr unshelve
 +
 +Remember to keep your branch updated:
 +    bzr merge --pull
 +
 +As a general rule of thumb, ''bzr help COMMAND'' gives you an explanation of any command and ''bzr help commands'' lists all available commands.
 +
 +//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.//
 +====== Push proposed changes ======
 +
 +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.
 +
 +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.
 +
 +<code bash>bzr push --remember lp:~USERNAME/midori/fix-bug1120383 && bzr lp-propose-merge lp:midori</code>
 +
 +lp-propose-merge command may not be working on some distributions like Arch or Fedora.
 +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.
 +
 +
 +**What happens to all the branches?**
 +
 +Leave the branches alone, **approved branches are cleared automatically** by Launchpad.
 +
 +For larger feature branches, **use the team** in Launchpad to allow other developers to work on the code with you.
 +
 +<code bash>bzr push --remember lp:~midori/midori/featuritis && bzr lp-propose-merge lp:midori</code>
 +
 +What if I want to help out on an **existing merge request** that I can't push to?
 +
 +<code bash>
 +bzr branch ~OTHERPERSON/midori/fix-bug1120383
 +cd fix-bug1120383
 +# make commits
 +bzr push lp:USERNAME~/midori/fix-bug1120383
 +bzr lp-propose-merge ~OTHERPERSON/midori/fix-bug1120383
 +</code>
 +
 +Updating a branch that may be out of sync with trunk:
 +
 +<code bash>
 +bzr pull
 +bzr: ERROR: These branches have diverged
 +bzr merge lp:midori
 +# Hand-edit conflicting changes
 +bzr resolve FILENAME
 +# If any conflicts remain continue fixing
 +bzr commit -m 'Merge lp:midori'
 +</code>
 +
 +Save a little bandwidth, **branch from an existing local copy** that you keep around:
 +
 +<code bash>
 +bzr branch lp:midori midori
 +bzr branch midori midori.fix-bug1120383
 +cd midori.fix-bug1120383
 +bzr pull lp:midori
 +</code>
 +
 +====== Backwards compatibility ======
 +As of Midori 0.5.4 the formula is:
 +  * Required dependencies need to be available on the previous stable [[https://apps.fedoraproject.org/packages/s/webkit|Fedora]] and [[http://packages.ubuntu.com/search?suite=quantal&keywords=webkit&searchon=names|Ubuntu]]
 +  * For reference [[http://openports.se/www/webkit|OpenBSD]]
 +  * Windows XP through 8 are to date ABI compatible, all dependencies are included
 +
 +^ package ^ F17 (2012-05-29) ^ U 12.10 (2012-10-18) ^
 +| glib2 | 2.32.4 | 2.34.0 |
 +| vala | 0.16.1 | 0.16 |
 +| gtk3 | 3.4.4 | 3.6.0 |
 +| gtk2 | 2.24.13 | 2.24.13 |
 +| soup | 2.38.1 | 2.40 |
 +| webkit | 1.8.3-1.fc17 | 1.10.0-0ubuntu1 |
 +====== Midori with(out) Granite ======
 +When built with Granite (-DUSE_GRANITE=1 or --enable-granite) there're a few key differences:
 +  * Preferences uses a [[http://valadoc.elementaryos.org/Granite/Granite.Widgets.StaticNotebook.html|Granite.Widgets.StaticNotebook]]
 +  * URL completion styling is slightly different
 +  * Clear Private Data uses **Granite.Widgets.LightWindow**
 +  * Edit Bookmark and Security Details use [[http://valadoc.elementaryos.org/Granite/Granite.Widgets.PopOver.html|Granite.Widgets.PopOver]] instead of Gtk.Window
 +  * Browser uses **Granite.Widgets.DynamicNotebook** instead of Gtk.Notebook
 +====== Midori for Windows ======
 +===== Dependencies =====
 +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:
 +
 +<code bash>yum install gcc vala intltool</code>
 +
 +For a native build
 +<code bash>yum install libsoup-devel webkitgtk3-devel sqlite-devel</code>
 +
 +For cross-compilation
 +<code bash>yum install mingw{32,64}-webkitgtk3 mingw{32,64}-glib-networking mingw{32,64}-gdb</code>
 +
 +Packages needed when assembling the archive
 +<code bash> yum install faenza-icon-theme p7zip mingw32-nsis</code>
 +
 +Installing those should get you the packages needed to successfully build and develop Midori for Win32.
 +
 +===== Building =====
 +For 32-bit builds:
 +<code bash>
 +mingw32-env
 +./configure --enable-gtk3 --prefix=/usr/i686-w64-mingw32/sys-root/mingw/
 +make
 +sudo make install</code>
 +
 +For 64-bit builds:
 +<code bash>
 +mingw64-env
 +./configure --enable-gtk3 --prefix=/usr/x86_64-w64-mingw32/sys-root/mingw/
 +make
 +sudo make install</code>
 +
 +Once built and tested you can assemble the Midori archive with a helper script
 +32-bit build:
 +<code bash>env MINGW_PREFIX="/usr/i686-w64-mingw32/sys-root/mingw" ./win32/makedist/makedist.midori</code>
 +64-bit build:
 +<code bash>env MINGW_PREFIX="/usr/x86_64-w64-mingw32/sys-root/mingw/" ./win32/makedist/makedist.midori x64</code>
 +
 +===== Testing =====
 +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.
 +
 +One way around it is to virtualize Windows on a Linux host and mount your MinGW directories as a network drive or shared folder.
 +
 +====== Jargon ======
 +    * freeze: a period of bug fixes only eg. 4/2 cycle means 4 weeks of features and 2 weeks to focus on resolving existing problems
 +    * MR: merge request, a branch proposed for review
 +    * ninja: an internal tab, usually empty label, used for taking screenshots
 +    * fortress: user of an ancient release like 0.4.3 as found on Raspberry Pie, Debian, Ubuntu
 +    * katze, sokoke, tabby: API names and coincidentally cat breeds