Merge lp:~mir-team/mir/project-page-in-docs into lp:~mir-team/mir/trunk

[Alexandros Frantzis]

doc: Use doxygen documentation to create a project page

doc: Use doxygen documentation to create a project page

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:483
http://jenkins.qa.ubuntu.com/job/mir-ci/37/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-quantal-amd64-ci/37//console

Click here to trigger a rebuild:
http://jenkins.qa.ubuntu.com/job/mir-ci/37//rebuild/?

review: Approve (continuous-integration)

[Alan Griffiths (alan-griffiths)]

I think we should update to avoid the duplication between HACKING and building_source_for_pc - but it doesn't cause any immediate harm.

review: Approve

=== added file 'doc/building_source_for_pc.md'
--- doc/building_source_for_pc.md	1970-01-01 00:00:00 +0000
+++ doc/building_source_for_pc.md	2013-03-11 14:27:24 +0000
@@ -0,0 +1,57 @@
+Building the source for a PC {#building_source_for_pc}
+============================
+
+Getting mir
+-----------
+
+Mir is a project on Launchpad (https://launchpad.net/mir). To grab a copy use
+the command:
+
+    $ bzr branch lp:mir
+
+
+Getting dependencies
+--------------------
+
+To succesfully build Mir there are a few packages required. The easiest way
+to get them is to use the packaging build dependencies:
+
+    $ apt-get install devscripts equivs cmake
+    $ mk-build-deps --install --tool "apt-get -y" --build-dep debian/control
+
+
+Building mir
+------------
+
+Mir is built using cmake. You first need to create the build directory and
+configure the build:
+
+    $ mkdir build
+    $ cd build
+    $ cmake .. (possibly passing configuration options to cmake)
+
+There are many configuration options for the mir project. The default options
+will work fine, but you may want to customize the build depending on your
+needs. The best way to get an overview and set them is to use the cmake-gui
+tool:
+
+    $ cmake-gui ..
+
+The next step is to build the source and run the tests:
+
+    $ make (-j8)
+    $ ctest
+
+Installing mir
+--------------
+
+To install mir just use the normal make install command:
+
+    $ make install
+
+This will install the mir libraries, executable, example clients and header
+files to the configured installation location (/usr/local by default). If you
+install to a non-standard location, keep in mind that you will probably need to
+properly set the PKG_CONFIG_PATH environment variable to allow other
+applications to build against mir, and LD_LIBRARY_PATH to allow applications to
+find the mir libraries at runtime.
 
=== added file 'doc/installing_prebuilt_on_android.md'
--- doc/installing_prebuilt_on_android.md	1970-01-01 00:00:00 +0000
+++ doc/installing_prebuilt_on_android.md	2013-03-11 14:27:24 +0000
@@ -0,0 +1,46 @@
+Installing pre-built packages on an Android device {#installing_prebuilt_on_android}
+==================================================
+
+Supported Devices
+-----------------
+
+The following devices have been tested with Mir:
+
+| Device             | Status |
+| ------------------ | ------ |
+| Nexus 7 (nvidia)   | tested |
+| Galaxy Nexus (SGX) | tested - needs special hybris for nvidia atm |
+| Nexus 4 (qualcomm) | in progress |
+
+Installing Mir
+--------------
+
+1. First you must install a phablet image on your device, by following the
+   directions at https://wiki.ubuntu.com/Touch/Install on one of the supported
+   devices. Once you have booted into the device with Ubuntu Touch ensure you
+   then connect the device to the internet.
+
+2. With your device connected via USB, type:
+
+       $ adb devices
+
+   just to ensure you are connected, then open the android shell:
+
+       $ adb root
+       $ adb shell
+
+3. In the adb shell, stop SurfaceFlinger, Android's compositing engine that
+   owns the display, and open the Ubuntu Touch shell:
+
+       # stop
+       # ubuntu_chroot shell
+
+4. Add the mir staging PPA to your device's sources list:
+
+       # apt-get install software-properties-common (to get the add-apt-repository command)
+       # add-apt-repository ppa:mir-team/staging
+       # apt-get update
+
+5. Install Mir:
+
+       # apt-get install mir libmirclient-demos
 
=== added file 'doc/installing_prebuilt_on_pc.md'
--- doc/installing_prebuilt_on_pc.md	1970-01-01 00:00:00 +0000
+++ doc/installing_prebuilt_on_pc.md	2013-03-11 14:27:24 +0000
@@ -0,0 +1,29 @@
+Installing pre-built packages on a PC {#installing_prebuilt_on_pc}
+=====================================
+
+1. Install raring if you haven' t done so already.  Uninstall any proprietary
+   drivers (-nvidia, -fglrx) and reboot on the FOSS drivers.
+
+2. Add the ppa:mir-team/staging. Note that besides mir itself, the PPA includes
+   custom builds of Mesa and Xorg drivers with support for mir:
+
+       sudo add-apt-repository ppa:mir-team/staging
+
+3. Update your package list:
+
+       sudo apt-get update
+
+4. Create the `/etc/apt/preferences.d/50-pin-mir.pref` file with the following contents:
+
+       Package: *
+       Pin: origin "private-ppa.launchpad.net"
+       Pin-Priority: 1001
+
+       Package: *
+       Pin: release o=LP-PPA-mir-team-staging
+       Pin-Priority: 1002
+
+5. Install mir and dist-upgrade:
+
+       sudo apt-get install mir
+       sudo apt-get dist-upgrade
 
=== modified file 'doc/mainpage.md'
--- doc/mainpage.md	2012-12-28 08:07:31 +0000
+++ doc/mainpage.md	2013-03-11 14:27:24 +0000
@@ -1,22 +1,59 @@
 Welcome to Mir {#mainpage}
 ==============
 
-Welcome to the world of Mir!
-
-Willkommen in der Welt von Mir!
-
-¡Bienvenido al mundo de Mir!
-
-Καλώς ήρθατε στον κόσμο του Mir!
+Mir is a next generation display server targeted as a replacement for the X
+window server system to unlock next-generation user experiences for devices
+ranging from Linux desktop to mobile devices powered by Ubuntu. The primary
+purpose of Mir is to enable the development of the next generation
+[Unity](http://unity.ubuntu.com).
+
+More detailed information about the motivation, scope, and high-level design
+of Mir can be found at http://wiki.ubuntu.com/MirSpec .
+
+Getting and installing Mir
+--------------------------
+
+### Using pre-built packages
+
+If you just want to try out mir, or write client applications, then the easiest
+way is to use the pre-built packages:
+
+ - \ref installing_prebuilt_on_pc
+ - \ref installing_prebuilt_on_android
+
+### Building and installing from source
+
+If you are curious about Mir internals or intend to contribute to it, you should
+get the source and build it:
+
+ - \ref building_source_for_pc
+
+Using Mir
+---------
+
+ - \ref using_mir_on_pc
+ - \ref using_mir_on_android
+
+Getting involved
+----------------
+
+The best place to ask questions and discuss about the Mir project is the
+#ubuntu-mir IRC channel on freenode.
+
+The Mir project is hosted on Launchpad: https://launchpad.net/mir
+
+Please file bug reports at: https://bugs.launchpad.net/mir
+
+The Mir development mailing list can be found at: https://lists.ubuntu.com/mailman/listinfo/Mir-devel
 
 Writing client applications
 ---------------------------
 
-1. \ref mir_client_library.h "Mir API Documentation"
-2. \subpage demo_client.c "demo_client.c: A simple mir client"
+ - \ref mir_client_library.h "Mir API Documentation"
+ - \subpage demo_client.c "demo_client.c: A simple mir client"
 
 Working on Mir code
 -------------------
 
-1. \ref md_README  "Mir Read me"
-2. \ref md_HACKING "Mir hacking guide"
+ - \ref md_README  "Mir Read me"
+ - \ref md_HACKING "Mir hacking guide"
 
=== added file 'doc/using_mir_on_android.md'
--- doc/using_mir_on_android.md	1970-01-01 00:00:00 +0000
+++ doc/using_mir_on_android.md	2013-03-11 14:27:24 +0000
@@ -0,0 +1,26 @@
+Using Mir on an Android device {#using_mir_on_android}
+==============================
+
+After installing mir on your device (see \ref installing_prebuilt_on_android),
+open the Android shell:
+
+    $ adb root
+    $ adb shell
+
+In the Android shell, stop SurfaceFlinger and open the Ubuntu touch chroot shell:
+
+    # stop
+    # ubuntu_chroot shell
+
+Now, start Mir and a client application:
+
+    # mir &
+    # some-mir-client (e.g. mir_demo_client_accelerated)
+
+Getting some example client applications
+----------------------------------------
+
+You can get some example programs by installing the `libmirclient-demos` package
+inside the Ubuntu touch chroot shell (see above):
+
+    # apt-get install libmirclient-demos
 
=== added file 'doc/using_mir_on_pc.md'
--- doc/using_mir_on_pc.md	1970-01-01 00:00:00 +0000
+++ doc/using_mir_on_pc.md	2013-03-11 14:27:24 +0000
@@ -0,0 +1,83 @@
+Using Mir on a PC {#using_mir_on_pc}
+=================
+
+Before you begin
+----------------
+
+Before you can use Mir you need to ensure you have the proper custom Mesa build
+installed. If you installed Mir using the packages from mir-team staging PPA
+(see \ref installing_prebuilt_on_pc), you should be good to go.
+
+If you built Mir from source code (see \ref building_source_for_pc), you need
+to ensure you are using the proper Mesa at runtime. You can do that by
+installing the Mesa packages manually from the staging PPA, or by building the
+custom Mesa yourself and ensuring it can be found by mir, e.g., by using
+LD_LIBRARY_PATH.
+
+Using Mir as system compositor with X
+-------------------------------------
+
+Note: for this to work you need to have Mir and all its dependencies (which
+include lightdm, Mesa and the Xorg drivers). The easiest way is to install
+pre-built packages from the staging PPA.
+
+To run X sessions under Mir, with Mir acting as the system compositor, edit
+your /etc/lightdm/lightdm.conf to look to look like this:
+
+    [SeatDefaults]
+    user-session=ubuntu
+    greeter-session=unity-greeter
+    type=mir
+
+Now restart lightdm:
+
+    $ sudo service lightdm restart
+
+In theory, you should now find yourself back in Ubuntu and not notice
+anything different. You can verify you're in mir several ways:
+
+    $ ps aux | grep mir
+    $ grep -i xmir /var/log/Xorg.0.log
+    $ ls -l /var/log/lightdm/mir.log
+
+Running Mir natively
+--------------------
+
+You can also run Mir natively. To do so, log in to VT1 (Ctrl+Alt+F1) _after_
+you are already logged in to X.  If you do so before then you will not be
+assigned adequate credentials to access the graphics hardware and will get
+strange errors.
+
+Note that you can switch back to X using Alt+F7. But it is very important to
+remember NOT to switch once you have any mir binaries running. Doing so will
+currently make X die (!).
+
+Now we want to run the mir server and a client to render something. The trick
+is that we need to make sure the mir server is easy to terminate before ever
+switching back to X. To ensure this, the server needs to be in the foreground,
+but starting before your client (in the background). To do this, you must:
+
+    $ (sleep 3; some-mir-client) & mir ; kill $!
+
+Wait 3 seconds and the client will start. You can kill it with Ctrl+C. REMEMBER
+to kill the mir processes fully before attempting to switch back to X or your X
+login will die.
+
+In case you accidentally killed your X login and ended up with a failsafe
+screen, you might find on subsequent reboots you can't log in to X at all any
+more (it instantly and silently takes you back to the login screen).  The fix
+for this is to log in to a VT and:
+
+    $ rm .Xauthority
+    $ sudo restart lightdm
+
+Getting some example client applications
+----------------------------------------
+
+If you installed mir using the packages from the mir-team staging PPA, you can
+get some example programs by installing the `libmirclient-demos` package:
+
+    $ sudo apt-get install libmirclient-demos
+
+If you are building from source you can find client applications in the bin/
+subdirectory of the build directory.