README.md
1[](https://circleci.com/gh/midori-browser/core)
2[](https://build.snapcraft.io/user/midori-browser/core)
3[](https://flathub.org/apps/details/org.midori_browser.Midori)
4[](https://www.midori-browser.org/telegram)
5[](https://twitter.com/midoriweb)
6[](https://www.midori-browser.org/donate)
7[](https://www.bountysource.com/teams/midori)
8[](https://www.patreon.com/midoribrowser)
9
10<p align="center">
11 <img src="icons/scalable/apps/org.midori_browser.Midori.svg"/>
12</p>
13
14<p align="center">
15 <b>Midori</b>
16 a lightweight, fast and free web browser
17</p>
18
19
20
21Midori is a lightweight yet powerful web browser which runs just as well on little embedded computers named for delicious pastries as it does on beefy machines with a core temperature exceeding that of planet earth. And it looks good doing that, too. Oh, and of course it's free software.
22
23**Privacy out of the box**
24
25* Adblock filter list support
26* Private browsing
27* Manage cookies and scripts
28
29**Productivity features**
30
31* Open a 1000 tabs instantly
32* Easy web apps creation
33* Customizable side panels
34* User scripts and styles a la Greasemonkey
35* Web developer tools powered by WebKit
36* Cross-browser extensions compatible with Chrome, Firefox, Opera and Vivaldi
37
38Please report comments, suggestions and bugs to:
39 https://github.com/midori-browser/core/issues
40
41Join [the #midori IRC channel](https://www.midori-browser.org/irc) on Freenode
42or [the Telegram group](https://www.midori-browser.org/telegram)!
43
44# Installing Midori on Linux
45
46If [your distro supports snaps](https://docs.snapcraft.io/core/)
47you can install the **latest stable** version of Midori
48[from the snap store](https://snapcraft.io/midori) with a single command:
49
50 snap install midori
51
52> **Spoilers:** For those more adventurous types out there, trying out the preview of the next version is only the switch of a channel away.
53
54You can also install Midori from [FlatHub](https://flathub.org/apps/details/org.midori_browser.Midori).
55
56 flatpak install flathub org.midori_browser.Midori
57
58# Installing Midori on Android
59
60You can opt-in for the [beta release on the Play Store](https://play.google.com/apps/testing/org.midori_browser.midori).
61
62# Building from source
63
64**Requirements**
65
66* [GLib](https://wiki.gnome.org/Projects/GLib) 2.46.2
67* [GTK](https://www.gtk.org) 3.12
68* [WebKitGTK](https://webkitgtk.org/) 2.16.6
69* [libsoup](https://wiki.gnome.org/Projects/libsoup) 2.48.0
70* [sqlite](https://sqlite.org) 3.6.19
71* [Vala](https://wiki.gnome.org/Projects/Vala) 0.30
72* GCR 2.32
73* [Libpeas](https://wiki.gnome.org/Projects/Libpeas)
74* [JSON-Glib](https://wiki.gnome.org/Projects/JsonGlib) 0.12
75
76Install dependencies on Astian OS, Ubuntu, Debian or other Debian-based distros:
77
78 sudo apt install cmake valac libwebkit2gtk-4.0-dev libgcr-3-dev libpeas-dev libsqlite3-dev libjson-glib-dev libarchive-dev intltool libxml2-utils
79
80Install dependencies on openSUSE:
81
82 sudo zypper in cmake vala gcc webkit2gtk3-devel libgcr-devel libpeas-devel sqlite3-devel json-glib-devel libarchive-devel fdupes gettext-tools intltool libxml2-devel
83
84Install dependencies on Fedora:
85
86 sudo dnf install gcc cmake intltool vala libsoup-devel sqlite-devel webkit2gtk3-devel gcr-devel json-glib-devel libpeas-devel libarchive-devel libxml2-devel
87
88Use CMake to build Midori:
89
90 mkdir _build
91 cd _build
92 cmake -DCMAKE_INSTALL_PREFIX=/usr ..
93 make
94 sudo make install
95
96> **Spoilers:** Pass `-G Ninja` to CMake to use [Ninja](http://martine.github.io/ninja) instead of make (install `ninja-build` on Ubuntu/ Debian).
97
98Midori can be **run without being installed**.
99
100 _build/midori
101
102# Testing
103
104## Unit tests
105
106You'll want to **unit test** the code if you're testing a new version or contributed your own changes:
107
108 xvfb-run make check
109
110## Manual checklist
111
112* Browser window starts up normally, with optional URL(s) on the command line
113* Tabs have icons, a close button if there's more than one and can be switched
114* Urlbar suggests from typed search or URL, completes from history and highlights key
115* Private data can be cleared
116* Shortcuts window shows most important hotkeys
117* Download button lists on-going and finished downloads
118* `javascript:alert("test")`, `javascript:confirm("test")` and `javascript:input("test")` work
119* Websites can (un)toggle fullscreen mode
120* Shrinking the window moves browser and page actions into the respective menus
121
122# Release process
123
124We're on a 8/4 cycle which means 8 weeks of features and 4 weeks of stabilization
125capped at a release once every 3 months ie. at the last of the third month.
126
127Update `CORE_VERSION` in `CMakeLists.txt` to `10.0`.
128Add a section to `CHANGELOG.md`.
129Add release to `data/org.midori_browser.Midori.appdata.xml.in`.
130
131 git commit -p -v -m "Release Midori 10.0"
132 git checkout -B release-10.0
133 git push origin HEAD
134 git archive --prefix=midori-v10.0/ -o midori-v10.0.tar.gz -9 HEAD
135
136Propose a PR for the release.
137Publish the release on https://github.com/midori-browser/core/releases
138Promote snap on https://snapcraft.io/midori/release to the `stable` channel
139
140# Troubleshooting
141
142Testing an installed release may reveal crashers or memory corruption which require investigating from a local build and obtaining a stacktrace (backtrace, crash log).
143
144 gdb _build/midori
145 run
146 ���
147 bt
148
149If the problem is a warning, not a crash GLib has a handy feature
150
151 env G_MESSAGES_DEBUG=all gdb _build/midori
152
153On Windows you can open the folder where Midori is installed and double-click gdb.exe which opens a command window:
154
155 file midori.exe
156 run
157 ���
158 bt
159
160To verify a regression you might need to revert a particular change:
161
162 # Revert only d54c7e45
163 git revert d54c7e45
164
165# Contributing code
166
167## Coding style and quality
168
169Midori code should in general have:
170
171 * 4 space indentation, no tabs
172 * Between 80 to 120 columns
173 * Use `//` or `/* */` style comments
174 * Call variables `animal` and `animal_shelter` instead of ~camelCase~
175 * Keep a space between functions/ keywords and round parentheses
176 * Prefer `new Gtk.Widget ()` over `using Gtk; new Widget ()`
177 * `Midori` and `GLib` namespaces should be omitted
178 * Don't use `private` specifiers (which is the default)
179 * Stick to standard Vala-style curly parentheses on the same line
180 * Cuddled `} else {` and `} catch (Error error) {`
181
182## Working with Git
183
184If you haven't yet, [check that GitHub has your SSH key](https://github.com/settings/keys).
185> **Spoilers:** You can create an SSH key with **Passwords and Keys** aka **Seahorse**
186> or `ssh-keygen -t rsa` and specify `Host github.com` with `User git` in your SSH config.
187> See [GitHub docs](https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/) for further details.
188
189[Fork the project on GitHub](https://help.github.com/articles/fork-a-repo).
190
191 # USERNAME is your GitHub username
192 git clone git@github.com:USERNAME/core.git
193
194Prepare to pull in updates from upstream:
195
196 git remote add upstream https://github.com/midori-browser/core.git
197
198> **Spoilers:** The code used to be hosted at `lp:midori` and `git.xfce.org/apps/midori` respectively.
199
200The development **master** (trunk, tip) is the latest iteration of the next release.
201
202 git checkout upstream/master
203
204Pick a name for your feature branch:
205
206 git checkout -B myfeature
207
208Remember to keep your branch updated:
209
210 git pull -r upstream master
211
212Tell git your name if you haven't yet:
213
214 git config user.email "<email@address>"
215 git config user.name "Real Name"
216
217See what you did so far
218
219 git diff
220
221Get an overview of changed and new files:
222
223 git status -u
224
225Add new files, move/ rename or delete:
226
227 git add FILENAME
228 mv OLDFILE NEWFILE
229 rm FILENAME
230
231Commit all current changes, selected interactively:
232
233 git commit -p -v
234
235If you have one or more related bug reports you should mention them
236in the commit message. Once these commits are merged the bug will
237automatically be closed and the commit log shows clickable links to the reports:
238
239 Fixes: #123
240
241If you've made several commits:
242
243 git log
244
245In the case you committed something wrong or want to amend it:
246
247 git reset --soft HEAD^
248
249If you end up with unrelated debugging code or other patches in the current changes
250it's sometimes handy to temporarily clean up.
251This may be seen as git's version of `bzr shelve`:
252
253 git stash save
254 git commit -p -v
255 git stash apply
256
257As a general rule of thumb, `git COMMAND --help` gives you an explanation
258of any command and `git --help -a` lists all available commands.
259
260Push your branch and **propose it for merging into master**.
261
262 git push origin HEAD
263
264This will automatically request a **review from other developers** who can then comment on it and provide feedback.
265
266# Extensions
267
268## Cross-browser web extensions
269
270The following API specification is supported by Midori:
271
272 manifest.json
273 name
274 version
275 description
276 background:
277 page: *.html
278 scripts:
279 - *.js
280 browser_action:
281 default_popup: *.html
282 default_icon: *.png
283 default_title
284 sidebar_action:
285 default_panel: *.html
286 default_icon: *.png
287 default_title
288 content_scripts:
289 js:
290 - *.js
291 css:
292 - *.css
293 manifest_version: 2
294
295 *.js
296 browser (chrome)
297 tabs
298 create
299 - url: uri
300 executeScript
301 - code: string
302 notifications
303 create
304 - title: string
305 message: string
306
307# Jargon
308
309* **freeze**: a period of bug fixes eg. 4/2 cycle means 4 weeks of features and 2 weeks of stabilization
310* **PR**: pull request, a branch proposed for review, analogous to **MR** (merge request) with Bazaar
311* **ninja**: an internal tab, usually empty label, used for taking screenshots
312* **fortress**: user of an ancient release like 0.4.3 as found on Raspberry Pie, Debian, Ubuntu
313* **katze, sokoke, tabby**: legacy API names and coincidentally cat breeds
314* web extension: a cross-browser extension (plugin) - or in a webkit context, the multi-process api
315
316# Midori for Android
317
318The easiest way to build, develop and test Midori on Android is with [Android Studio](https://developer.android.com/studio/#downloads) ([snap](https://snapcraft.io/android-studio)).
319
320When working with the command line, setting `JAVA_HOME` is paramount:
321
322 export JAVA_HOME=/snap/android-studio/current/android-studio/jre/
323
324Afterwards you can run commands like so:
325
326 ./gradlew lint test
327
328# Midori for Windows
329
330## For Linux developers
331
332### Dependencies
333
334Midori 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
338For a native build
339
340 yum install libsoup-devel webkitgtk3-devel sqlite-devel
341
342For cross-compilation
343
344 yum install mingw{32,64}-webkitgtk3 mingw{32,64}-glib-networking mingw{32,64}-gdb mingw{32,64}-gstreamer-plugins-good
345
346Packages needed when assembling the archive
347
348 yum install faenza-icon-theme p7zip mingw32-nsis greybird-gtk3-theme
349
350Installing those should get you the packages needed to successfully build and develop Midori for Win32.
351
352### Building
353
354For 32-bit builds:
355
356 mkdir _mingw32
357 cd _mingw32
358 mingw32-cmake .. -DCMAKE_INSTALL_PREFIX=/usr/i686-w64-mingw32/sys-root/mingw -DCMAKE_VERBOSE_MAKEFILE=0
359 make
360 sudo make install
361
362For 64-bit builds:
363
364 mkdir _mingw64
365 cd _mingw64
366 mingw64-cmake .. -DCMAKE_INSTALL_PREFIX=/usr/x86_64-w64-mingw32/sys-root/mingw -DCMAKE_VERBOSE_MAKEFILE=0
367 make
368 sudo make install
369
370Once built and tested you can assemble the Midori archive with a helper script
371
37232-bit build:
373
374 env MINGW_PREFIX="/usr/i686-w64-mingw32/sys-root/mingw" ./win32/makedist/makedist.midori
375
37664-bit build:
377
378 env MINGW_PREFIX="/usr/x86_64-w64-mingw32/sys-root/mingw/" ./win32/makedist/makedist.midori x64
379
380### Testing
381
382For testing your changes a real system is recommended because WebKitGTK+ doesn't work properly under Wine. Mounting your MinGW directories as a network drive or shared folder in a Windows VM is a good option.
383
384## For Windows developers
385
386### Prerequisites
387
388* [MinGW](http://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win64/Personal%20Builds/rubenvb/gcc-4.8-release/x86_64-w64-mingw32-gcc-4.8.0-win32_rubenvb.7z/download) *mingw64 rubenvb*/ gcc 4.8.0 ([Releases](http://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win64/Personal%20Builds/rubenvb/gcc-4.8-release))
389* [7zip](http://www.7-zip.org/download.html) ([32bit Installer](http://downloads.sourceforge.net/sevenzip/7z920.exe)) to extract archives
390* [Python3](http://www.python.org/download/releases/3.3.5) to use **download-mingw-rpm.py**.
391* [download-mingw-rpm.py](https://github.com/mkbosmans/download-mingw-rpm/blob/master/download-mingw-rpm.py) to fetch and unpack rpm's
392* [Msys](http://sourceforge.net/projects/mingw-w64/files/External%20binary%20packages%20%28Win64%20hosted%29/MSYS%20%2832-bit%29/MSYS-20111123.zip/download) contains shell and some small utilities
393* [CMake](http://www.cmake.org/cmake/resources/software.html) ([Installer](http://www.cmake.org/files/v2.8/cmake-2.8.12.2-win32-x86.exe))
394* [Vala](http://ftp.gnome.org/pub/gnome/sources/vala/0.20/vala-0.20.0.tar.xz)
395
396
397> **Spoilers:** 32-bit versions are known to be more stable at the time of this writing.
398
399### Using download-mingw-rpm.py
400
401* Launch `cmd.exe` and navigate to the folder where the script was saved.
402* Make sure that Python can access `7z.exe`.
403* Run the following command and wait for it to extract the packages into your current directory:
404* `c:\Python33\python.exe download-mingw-rpm.py -u http://ftp.wsisiz.edu.pl/pub/linux/fedora/linux/updates/18/i386/ --deps mingw32-webkitgtk mingw32-glib-networking mingw32-gdb mingw32-gstreamer-plugins-good`
405
406See [Fedora 18 packages](http://dl.fedoraproject.org/pub/fedora/linux/releases/18/Everything/i386/os/Packages/m/).
407
408> **Spoilers:** Use `msys.bat` to launch a shell
409