View source for Embedding/IPCLiteAPI

== Lite-weight Embedding API for Mozilla based applications with native UI. ==
<p>Basic architecture is very close to [http://trac.webkit.org/wiki/WebKit2 WebKit2], and [http://browser.garage.maemo.org/docs/browser_paper.html MicroB]

== Story ==
=== Mozilla has bunch of technologies integrated recently: ===
* [https://wiki.mozilla.org/Platform/GFX/OffMainThreadCompositing OMTC - Off Main thread compositing - keeping Gecko/XPCOM and Compositor in separate threads (Android Firefox)]
* [https://wiki.mozilla.org/Electrolysis IPC - Multiprocess rendering - keeping Gecko/XPCOM and Compositor in separate processes (Firefox OS, Desktop Firefox Plugins)]

In order to build Simple browser with native UI (Gtk/Qt/UiKit) similar to Android Firefox with Java UI, some internal API need to be exposed.
Goal of this project to provide Generic embedding API which could be easily wrapped without bunch of extra code into Toolkit specific Widgets, and embed these widgets into platform UI applications.

</p><p>Benefits of new architecture comparing to default [https://wiki.mozilla.org/Embedding/NewApi mozilla embedding]:</p>
<pre class="_fck_mw_lspace">* No XUL/XPCOM heavy content in UI process/Thread (Best memory footprint (process case), fast startup)
* Process/Thread communication between UI and Content(Gecko/XPCOM) Thread/Process - built on current Mozilla Chromium/IPDL implementation ([https://developer.mozilla.org/en-US/docs/IPDL/Tutorial IPDL Tutorial])
* Rendering based on Shadow/Shadowable layers tree which provide MultiThread/Process responsive rendering (same as content rendering in XUL Mobile FF/OMTC Android Firefox/Firefox OS)
* Multi process model provide ability to load memory greedy content in child process and kill it without increasing memory usage for Main UI application process
</pre>

== New embedding expected initialization sequence ==
 1. Native UI startup (android UI thread view or Gtk/Qt/UIKit event loop)
 2. Load EmbedLite library and start point API (can be called in parallel thread)
    LoadEmbedLite(argc, argv);

 3. Get EmbedLite application object, which allow to start Gecko in Child-Thread/Process, and create rendering views
    EmbedLiteApp* embedapp = XRE_GetEmbedLite();
 4. Setup EmbedLite application listener (Some notifications about main app lifecycle)
    EmbedLiteAppListener[Derived]* listener = new EmbedLiteAppListener[Derived]();
    embedapp->SetListener(listener);
 5. Startup Embedding, blocking call, better to start UI first, and call this in some main loop event
    EmbedLite will not freeze application here, and continue native events processing along with Chromium Messages.
    embedapp->Start(EmbedLiteApp::EMBED_THREAD/PROCESS);

  [https://github.com/romaxa/mozilla-central/blob/embedlite/embedding/embedlite/tests/embedLiteCoreInitTest.cpp Core Embed Initialization example]

 6. After EmbedLiteAppListener[Derived] received "Initialized" notification, new EmbedLiteView can be created with:
    EmbedLiteView* view = embedapp->CreateView();
    And setup related EmbedLiteViewListener in order to receive notifications from View actions (title,progress,invalidate et.c.)
    view->SetListener(MyEmbedLiteViewListener);
 
  [https://github.com/romaxa/mozilla-central/blob/embedlite/embedding/embedlite/tests/embedLiteViewInitTest.cpp View Embed Initialization example]

 

=== Communication between UI and content process ===
 * Load remote content JS (privileged script with full access) and interact using MessageMessenger (send/receive JSON messages)
 * Use embed messaging API (observe broadcast messages)
 * Build Custom Gecko C++/JS extensions

== [http://hg.mozilla.org/users/romaxa_gmail.com/embedipc_queue Source code path queue] ==
== [https://bugzilla.mozilla.org/show_bug.cgi?id=713681 BMO Bug 713681(IPC)]  ==
== [https://bugzilla.mozilla.org/show_bug.cgi?id=746800 BMO Bug 746800(OMTC)]  ==

== Development Build instructions: ==

Clone repository with submodules structure

<pre>
git clone git://github.com/tmeshkova/xulrunner-package.git
</pre>

Build it with simple script run:
<pre>
cd xulrunner-package

# Pull all latest changes
./pull.all.sh

# Check list of available options
./build.sh -h 

# Haramttan
./build.sh -t harmattan

# Fremantle
./build.sh -t fremantle

# Desktop - Qt is default
./build.sh -t desktop

# For debug builds add -d argument

</pre>

== Packaged Build instructions (debian desktop, N9): ==

Clone repositories

<pre>
mkdir ~/mozembed
cd ~/mozembed
# Gecko Engine with EmbedLite API
git clone git://github.com/tmeshkova/mozilla-central.git

# Embedlite toolkit independent components (History,prompt et.c.)
git clone git@github.com:tmeshkova/embedlite-components.git

# qtmozembed - Qt wrapper library around EmbedLite API for quick integration into QML.
git clone git@github.com:tmeshkova/qtmozembed.git

# qmlmozbrowser UI application which works as simple reference UI
git clone git@github.com:tmeshkova/qmlmozbrowser.git
</pre>

Build with dpkg-buildpackage
<pre>
cd ~/mozembed/mozilla-central
dpkg-buildpackage -us -uc -b -nc
dpkg -i ../xulrunner*.deb

cd ~/mozembed/embedlite-components
dpkg-buildpackage -us -uc -b -nc
dpkg -i ../embedlite-components*.deb

cd ~/mozembed/qtmozembed
dpkg-buildpackage -us -uc -b -nc
dpkg -i ../libqtmozembed*.deb

cd ~/mozembed/qmlmozbrowser
dpkg-buildpackage -us -uc -b -nc
dpkg -i ../qmlmozbrowser*.deb
</pre>

# Simple test to check
<pre>
/usr/lib/xulrunner-21.0a1/embedLiteCoreInitTest
</pre>

# For development it is better to link xulrunner objdir to system (on desktop or on device with ~/mozembed mounted via NFS)
<pre>
cd ~/mozembed/mozilla-central
./link_to_system.sh obj-xr-qt /usr
# for embedlite-components, qtmozembed, qmlmozbrowser just run 
./link_to_system.sh
</pre>

Finally run test example:
<pre>
qmlMozEmbedTest -url about:license
</pre>

== Try, Test, Report, Contribute: ==

Fell free to test it, submit issues to github issue tracker, or even better fork it, fix it, contribute changes via Pull Requests.

== Pre compiled binaries: ==

=== Mer (ARMv7 hardfp) ===
http://romaxa.info/mer/mozbuild.tar.gz

=== Harmattan ===
http://romaxa.info/mer/mozbuildhm.tar.gz

=== Qt-Desktop and BeagleBoard Ubuntu ===
http://romaxa.info/fennec/IPCEmbedding/

== Run test examples: ==
<pre>
cd obj-*/dist/bin

Basic core test
./embedLiteCoreInitTest

EmbedLiteAPI wrapped into qt/qml widget
Qt only, qml based UI with scrolling and zooming (no clicks):
./qmlMozEmbedTest -url linux.org.ru

</pre>

== Basic view of new architecture: ==

[[File:EmbedIPC-basic.png]]