Subject: Improving Our Docs

From: Jono Bacon <[email-masked]>
Date: Thu, 20 Jun 2013 15:55:34 -0700

Hi,

Some time ago I asked Daniel Holbach to coordinate with the Mir team to
improve the documentation on wiki.ubuntu.com/Mir to make it simple to
participate in Mir development. I think Daniel and the team did a great job
there.

There are now some other documentation needs that I think we need in light
of recent discussions:

 * How to write a a Mir backend for a window manager / toolkit. This could
really help other projects that are interested in supporting Mir.

 * How to build Mir for non-Ubuntu systems. Jef Spaleta shared this concern
with me this week, and I think some more generic build instructions would
be useful.

 * How to write a driver that supports Mir. This could be of interest for a
hardware company who is interested in exploring Mir support for their
hardware.

I have Daniel to take care of working with our community and Mir engineers
to put together these docs. Is anyone willing to help contribute to putting
this content together as part of this effort?

Thanks!

   Jono

-- 
Jono Bacon
Ubuntu Community Manager
www.ubuntu.com / www.jonobacon.org
www.identi.ca/jonobacon www.twitter.com/jonobacon

---

From: Robert Ancell <[email-masked]>
Date: Fri, 21 Jun 2013 11:04:22 +1200

Sounds great! Note that there is some documentation on
http://unity.ubuntu.com/mir/, for example the "Writing server applications"
is a start on "Mir backend for a window manager" and "Writing client
applications" should be expanded to mention using the API for toolkits
specifically.

These documents are automatically generated from the source in lp:mir -
merges welcome!

There is some work being done to improve driver documentation, I'll let
those working on that give more details.

--Robert

On Fri, Jun 21, 2013 at 10:55 AM, Jono Bacon <[email-masked]> wrote:

>  * How to build Mir for non-Ubuntu systems. Jef Spaleta shared this
> concern with me this week, and I think some more generic build instructions
> would be useful.
>
>  * How to write a driver that supports Mir. This could be of interest for
> a hardware company who is interested in exploring Mir support for their
> hardware.
>
> Mir-devel mailing list
> [email-masked]
> Modify settings or unsubscribe at:
> https://lists.ubuntu.com/mailman/listinfo/mir-devel
>
>

---

From: Daniel van Vugt <[email-masked]>
Date: Fri, 21 Jun 2013 10:08:17 +0800

Just some notes to consider before anyone tries to write docs:

* How to write a a Mir backend for a window manager / toolkit. This 
could really help other projects that are interested in supporting Mir.
  - Backend for a "window manager": This means a shell, linking to 
libmirserver. I may be alone in thinking this, but am not comfortable we 
have our class structure (via libmirserver) quite right to go 
documenting this yet. But still, you can look at examples/demo-shell/*
which some might find surprising to hear is intended to be a totally 
generic shell with no links to Unity. It still needs more functionality 
yet, though.
  - Toolkit: This means a client linking to libmirclient. The client API 
is *almost* completely stable now. Changes are minimal these days so 
it's safe to document, and the basics are documented:
    http://unity.ubuntu.com/mir/group__mir__toolkit.html

* How to build Mir for non-Ubuntu systems. Jef Spaleta shared this 
concern with me this week, and I think some more generic build 
instructions would be useful.
  - I totally agree we need to make building everything-Mir easier, for 
everyone. We have had discussions and will work on easing the process. I 
think it could be documented now but that documentation will of course 
evolve with the projects themselves.

* How to write a driver that supports Mir. This could be of interest for 
a hardware company who is interested in exploring Mir support for their 
hardware.
   - This can not be documented until we have at least had a first 
attempt at making it possible to load external code:
     https://bugs.launchpad.net/mir/+bug/1118909

- Daniel

On 21/06/13 06:55, Jono Bacon wrote:
> improve the documentation on wiki.ubuntu.com/Mir
> <http://wiki.ubuntu.com/Mir> to make it simple to participate in Mir
> development. I think Daniel and the team did a great job there.
>
> There are now some other documentation needs that I think we need in
> light of recent discussions:
>
>   * How to write a a Mir backend for a window manager / toolkit. This
> could really help other projects that are interested in supporting Mir.
>
> concern with me this week, and I think some more generic build
> instructions would be useful.
>
>   * How to write a driver that supports Mir. This could be of interest
> for a hardware company who is interested in exploring Mir support for
> their hardware.
>
> I have Daniel to take care of working with our community and Mir
> engineers to put together these docs. Is anyone willing to help
> contribute to putting this content together as part of this effort?
>
> Thanks!
>
>     Jono
>
> --
> Jono Bacon
> Ubuntu Community Manager
> www.ubuntu.com <http://www.ubuntu.com> / www.jonobacon.org
> <http://www.jonobacon.org>
> www.identi.ca/jonobacon <http://www.identi.ca/jonobacon>
> www.twitter.com/jonobacon <http://www.twitter.com/jonobacon>
>
>

---

From: Jono Bacon <[email-masked]>
Date: Thu, 20 Jun 2013 21:50:53 -0700

On Thu, Jun 20, 2013 at 7:08 PM, Daniel van Vugt <
[email-masked]> wrote:

> have our class structure (via libmirserver) quite right to go documenting
> this yet. But still, you can look at examples/demo-shell/*

Makes sense, but in the interim, having this information and pointing to
examples/demo-shell would likely help. Any idea when we the class structure
may be more stabilized?

>  - Toolkit: This means a client linking to libmirclient. The client API is
> *almost* completely stable now. Changes are minimal these days so it's safe
> to document, and the basics are documented:
>    http://unity.ubuntu.com/mir/**group__mir__toolkit.html<http://unity.ubuntu.com/mir/group__mir__toolkit.html>
>
>
So this looks API documentation, which is useful, but I was thinking it
would be more useful to have a short tutorial or walkthrough the steps of
how to create a client. Is this something someone would be willing to
volunteer to write and link on the Mir wikisite?

> evolve with the projects themselves.
Makes sense. Maybe this documentation will be better served as a wiki page.

Jef, if the team would be happy to work on this, would you be happy to help
document building Mir for Fedora?

>   - This can not be documented until we have at least had a first attempt
> at making it possible to load external code:
>     https://bugs.launchpad.net/**mir/+bug/1118909<https://bugs.launchpad.net/mir/+bug/1118909>
>
>
When Alan fixes this bug and we are in a position to do this, would be
happy to have a crack at writing something here?

Thanks, Daniel!

   Jono

>> www.identi.ca/jonobacon <http://www.identi.ca/**jonobacon<http://www.identi.ca/jonobacon>
>> >
>> www.twitter.com/jonobacon <http://www.twitter.com/**jonobacon<http://www.twitter.com/jonobacon>
>> >
>>
>>
>>
> --
> Mir-devel mailing list
> Modify settings or unsubscribe at: https://lists.ubuntu.com/**
> mailman/listinfo/mir-devel<https://lists.ubuntu.com/mailman/listinfo/mir-devel>
>

---

From: Alan Griffiths <[email-masked]>
Date: Fri, 21 Jun 2013 09:22:06 +0100

On 21/06/13 05:50, Jono Bacon wrote:
>
>
>     * How to write a driver that supports Mir. This could be of
>     interest for a hardware company who is interested in exploring Mir
>     support for their hardware.

Fixing that bug is a small part of the problem (FWIW I should be
proposing a fix later today).

The core of Mir is GPL3 and linking to that is likely to introduce
issues for some hardware companies.

The APIs involved are:

  1. not part of a fixed or versioned ABI; and,
  2. not documented in enough detail for this usage.

---

From: Daniel Holbach <[email-masked]>
Date: Fri, 21 Jun 2013 11:27:10 +0200

Hello,

> instructions would be useful.

In https://bugs.launchpad.net/mir/+bug/1193261 Alan asks if the pieces
of text under "Building and installing from source" linked from
http://unity.ubuntu.com/mir/ aren't good enough yet.

CCing Jef, maybe you could give some feedback on this thread or on the
bug report mentioned above?

Maybe the "Building and installing from source" docs are good enough and
we just need to refer to them from https://wiki.ubuntu.com/Mir?

> contribute to putting this content together as part of this effort?

I just filed these bugs to keep track of the docs related improvements:

	https://bugs.launchpad.net/mir/+bugs?field.tag=docs

Have a great day,
 Daniel

-- 
Get involved in Ubuntu development! developer.ubuntu.com/packaging
Stay up to date: follow @ubuntudev on identi.ca/twitter.com/facebook.com

---

From: Jeff Spaleta <[email-masked]>
Date: Fri, 21 Jun 2013 09:20:13 -0800

Morning,

For starters to smoke test Mir I need:
The... canonical...set of branches for Mir and its dependencies as
used in current Mir development workflow necessary to smoke test a
binary mir in a locally controlled clean build environment
(/usr/local) so that I can use environment variables to switch from
the environment provided dependencies to the mir specific dependencies
if the environment does not provide them.  Current build from source
and test implicitly assumes you are going to pull patched deps from
ppa staging which implicitly assumes a very specific environment thus
a non-starter for anyone not using that environment.

If upstream stock releases of dependencies will suffice, the minimum
release number for that dependancy is fine (and this is generally
cullable from the debian packaging when general assumption is you are
not relying on vendor patches in that dependency and the stock version
is meant to be sufficient..caveats apply of course).

When its known that testability requires significant downstream
patchsets be applied to a stock upstream release or development tip,
then the bzr/git branch that matches that on-going development of that
patched dependency should be provided in the build from source
instructions instead of an upstream release number for that dep. So as
of now I understand that to mean the Mir lp trunk branch and ROAF's
mesa and xserver branches with mir specific changes should be included
as part of the build from source instructions .  In the future I
expect that the mesa/xserver branch urls can be replaced with upstream
development branch urls once necessary patches are upstreamed.

Based on my current understanding of the codebase, I think should be
able to get a clean build/testable build of mir from sources on a
CentOS 5.x or Debian stable system or for that matter any active U
LTS, if the necessary deps versions/branches are documented, all
without replacing any system packages and destabilizing the running
system. I guess I'll find out if that's true soon enough.

Beyond local build from source...
To have any hope of actually getting this packaged officially in
Fedora (and I daresay other distributions such as Debian), there must
be a way forward that does not require distribution level patching of
Mir's depchain, so upstreaming the Mir enabling patches for codebases
outside of Mir itself is somewhat important in the medium term.  But
before we burn that particular bridge, I have to be able to at least
smoke test Mir in a clean environment of my choosing.

-jef

---

From: Jono Bacon <[email-masked]>
Date: Mon, 1 Jul 2013 15:22:23 -0700

Can anyone respond to Jef to move this along for build instructions for
other platforms?

---

From: Jono Bacon <[email-masked]>
Date: Mon, 1 Jul 2013 15:23:24 -0700

Hi All,

This thread has gone quiet. Daniel, I asked you to focus in on improving
our docs here, can you provide an update to the list?

I think our priorities are:

 * Build instructions for other distros.
 * Guide to building Mir support for a WM.

Thanks!

   Jono

---

From: Robert Ancell <[email-masked]>
Date: Tue, 2 Jul 2013 17:14:55 +1200

Hi Jeff,

I figure you have them, but for an official statement to the list the
branches you need are:

1. lp:mir
2. lp:unity-system-compositor
3. lp:~mir-team/lightdm/unity [1]
4. https://github.com/RAOF/mesa branch egl-platform-mir
5. https://github.com/RAOF/xserver branch vladmir

1 and 2 are CMake and 3, 4 and 5 are autotools. So they should in theory
work fine in /usr/local though it's probably not well tested.

Dependencies are specified in the build systems for each and as far as I
know don't require anything non-standard over what their upstreams provide.

--Robert

[1] Though I have just merged the main portion of this into lp:lightdm,
it's probably safer to use the ~mir-team branch at this point in time.

---

From: Daniel van Vugt <[email-masked]>
Date: Tue, 02 Jul 2013 16:32:36 +0800

I think Robert's list is a superset. Technically you only need two of 
them, in theory:
    1. lp:mir
    4. https://github.com/RAOF/mesa branch egl-platform-mir
That's enough to run a basic server and native client, in a VT.

But Robert's list below is the full set of projects the Mir team is 
looking after. Canonical also has other Mir-related projects not on the 
list, such as the Qt Unity8 work.

On 02/07/13 13:14, Robert Ancell wrote:
> Hi Jeff,
>
> On Sat, Jun 22, 2013 at 5:20 AM, Jeff Spaleta
> <[email-masked] <mailto:[email-masked]>> wrote:
>
>     Morning,
>

---

From: Robert Ancell <[email-masked]>
Date: Tue, 2 Jul 2013 20:45:20 +1200

Sorry, XMir on the brain :)

Yes, I should clarify that is the packages required to get an XMir based
system set up which is the most practically useful system to set up
currently. As Daniel pointed out 1 and 4 are only required to setup a test
Mir server and run some demo client.

--Robert

On Tue, Jul 2, 2013 at 8:32 PM, Daniel van Vugt <
[email-masked]> wrote:

>> <[email-masked] <mailto:jspaleta@**fedoraproject.org<[email-masked]>>>
>> wrote:
>>
>>     Morning,
>>
>> 5. https://github.com/RAOF/**xserver <https://github.com/RAOF/xserver>branch vladmir
>>

---

From: Daniel Holbach <[email-masked]>
Date: Tue, 02 Jul 2013 12:46:38 +0200

Hello everybody,

> our docs here, can you provide an update to the list?

Sure.

>  * Build instructions for other distros.

I talked to several people and together with consulting
http://unity.ubuntu.com/mir/building_source_for_pc.html and some help
from IRC, I'd say that the following should help getting mir builds up
and running.  (Please let me know if any essential
options/flags/build-dependencies are missing.)

I tested this in an Ubuntu chroot today:

# for Mir
<install cmake cmake-data doxygen xsltproc graphviz libboost-all-dev
         protobuf-compiler libegl1-mesa-dev libgles2-mesa-dev
         libglm-dev libprotobuf-dev pkg-config libgoogle-glog-dev
         liblttng-ust-dev libxkbcommon-dev valgrind libdrm-dev
         libgbm-dev> (note that some package names might be different
                      for other distros)
bzr branch lp:mir
cd mir; mkdir build; cd build
cmake ..
make -j8
sudo make install

# for mesa
<install bison expat libexpat-dev llvm libxcb-xfixes0-dev autoconf
         automake libtool libxml2-dev python-libxml2 flex intltool
         llvm-3.2-dev>
git clone https://github.com/RAOF/mesa
cd mesa
./autogen.sh --with-egl-platforms=mir,drm
make
sudo make install

# for xserver
<install xutils-dev libpixman-1-dev libgcrypt11-dev x11proto-xcmisc-dev
         libxkbfile-dev x11proto-xf86dri-dev x11proto-render-dev
         x11proto-composite-dev x11proto-xinerama-dev
         x11proto-randr-dev x11proto-xf86bigfont-dev x11proto-video-dev
         x11proto-scrnsaver-dev libxfont-dev x11proto-resource-dev
         x11proto-record-dev libpciaccess-dev xfonts-utils
         x11proto-bigreqs-dev>
git clone https://github.com/RAOF/xserver
cd xserver
./autogen.sh --enable-xmir
make -j8

Unfortunately during the last step I run into
http://paste.ubuntu.com/5835758/ - any help with resolving this would be
appreciated.

Once this is resolved we should be able to update our docs and have a
"build on non-Ubuntu" section, I guess.

I'll udpate https://bugs.launchpad.net/mir/+bug/1193261 with my findings.

>  * Guide to building Mir support for a WM.

I talked to several people and the consensus seemed to be that things
are moving and changing too quickly right now to be able to document
anything which doesn't have to be changed in a couple of weeks/days
again. In https://bugs.launchpad.net/mir/+bug/1193260 I suggested to
link to code examples.

Have a great day,
 Daniel

-- 
Get involved in Ubuntu development! developer.ubuntu.com/packaging
Follow @ubuntudev on identi.ca/twitter.com/facebook.com/G+

---

From: Jeff Spaleta <[email-masked]>
Date: Tue, 2 Jul 2013 08:31:06 -0800

Morning,

The list of psuedo-pretty instructions looks more than sufficient in
terms of level of detail.  Just one suggestion.
If the set of deps for the patched xserver and mesa are the same as
development tip xserver and mesa, its sufficient to just say that. If
there are any deps beyond what those upstream projects need to build
their development tip, then it is sufficent and necessary to just name
those.  Or to restart simply:
"Assume the system is prepped to build  the unpatched upstream
dependences as a starting point"

And a couple of other questions.

Daniel, assuming Mir builds.. is this sufficient to get Mir up and
running and test mir native clients in a repeatable way as part the
documented instructions for testing? Same with xmir.  If I want to
smoke fvwm2 on top of xmir, is this sufficient? Or do I need to also
build mir capable lightdm as the dm to manage creating the xmir backed
session?

I am a bit concerned that Daniel and  Robert are suggesting different
git branches for the patched mesa and xserver.  Are they equivalent
for basic smoke testing? Perhaps you guys need to huddle up and come
to agreement as to which specific branches should be codified for
externals now to pull when doing the first build from source,
especially now a new ppa has been created and codified in the docs to
replace the staging ppa. is the new ppa automation pulling for the
branches that Robert pointed me to?  I would hope that the specific
branches in the build from source instructions match what is getting
pulled into the ppa automation.

-jef

---

From: Robert Ancell <[email-masked]>
Date: Wed, 3 Jul 2013 10:40:00 +1200

> It appears you want the vladmir-ubuntu branch, not the vladmir branch
(which is out of date).

---

From: Daniel Holbach <[email-masked]>
Date: Wed, 03 Jul 2013 09:17:34 +0200

Hello Robert,

> It appears you want the vladmir-ubuntu branch, not the vladmir branch

How would I go about using this branch instead? How would you change the
instructions I posted?

Have a great day,
 Daniel

---

From: Daniel Holbach <[email-masked]>
Date: Wed, 03 Jul 2013 09:20:15 +0200

Hello Jeff,

Thanks for your suggestions!

> dependences as a starting point"

Yes, I guess that makes sense. I posted them on the list to make sure
that more knowledgeable engineers could have a look over them and see if
there's anything in there which probably doesn't make sense. It's the
minimum of what I had to install in a chroot to make the build work.

> build mir capable lightdm as the dm to manage creating the xmir backed

I'll leave this question to the more experienced developers.

> pulled into the ppa automation.

I just tried to make use of the branches which Robert suggested. If
anyone can help specify this any further, let me know.

Have a great day,
 Daniel

---

From: Robert Ancell <[email-masked]>
Date: Thu, 4 Jul 2013 09:01:36 +1200

I pointed this out to Chris and he changed the default branch in github. So
a fresh clone should do it.

---

From: Robert Ancell <[email-masked]>
Date: Thu, 4 Jul 2013 09:04:15 +1200

> I'll leave this question to the more experienced developers.

You don't need to run LightDM to run Mir or XMir.

> anyone can help specify this any further, let me know.
Not sure which Daniel is being referred to but as far as I can tell we are
referring to the same branches.

---

From: Jeff Spaleta <[email-masked]>
Date: Wed, 3 Jul 2013 15:34:06 -0800

Same branches? Really?  It's not clear to me at all. Regardless of who
said what... so far in this discussion I've seen 3 sets of
instructions with regard to mesa xserver

To be clear:
So far in this thread I have been pointed to both
https://github.com/RAOF/mesa branch egl-platform-mir
https://github.com/RAOF/xserver branch vladmir

As well as just
https://github.com/RAOF/mesa
https://github.com/RAOF/xserver
with no specific branch indicated.

And then it was stated that the vladmir branch is out of date and
vladmir-ubuntu should be used instead.
Based on the evolving discussion this week, I sort of feel like if I
ask again next week, the correct branches with change again.
Please understand that you may view this back and forth on this list
as valid instructions all pointing to the same thing. But right now...
I see 3 different sets of git branch instructions on this list and no
consensus as to which branches are supposed to be codified in the
instructions at unity.ubuntu.com/mir with regard to custom mesa and
xserver.

Please huddle up on irc or wherever and get some consensus on which
mesa and xserver branches are the correct ones and then document those
in the build from source instructions meant to be used in " building
the custom Mesa yourself and ensuring it can be found by Mir" as
described on this page:
http://unity.ubuntu.com/mir/using_mir_on_pc.html  This page makes
passing reference to to need for custom builds of these things but
provides no reference to how to obtain them other than the ppa build.

And I'll re-iterate that there is still no reference to any mesa or
xserver branch at
http://unity.ubuntu.com/mir/building_source_for_pc.html just mir
itself.  This continues to be insufficient for any one looking to
build and test Mir from source instead of the ppa. So can you please
get which ever mesa and xserver branches are needed enshrined in those
docs.

-jef

---

From: Robert Ancell <[email-masked]>
Date: Thu, 4 Jul 2013 12:02:18 +1200

> with no specific branch indicated.

In the first set I explicitly listed the particular branch in use, in the
second case they are not specified - though they default to the same
branches. vladmir was supposed to be the correct branch for the xserver,
but it was out of date so now the default is vladmir-ubuntu. If it wasn't
confusing, it wouldn't be git.

---

From: Robert Ancell <[email-masked]>
Date: Fri, 12 Jul 2013 10:04:21 +1200

http://unity.ubuntu.com/mir/building_source_for_pc.html is now updated with
more instructions.

On Thu, Jul 4, 2013 at 11:34 AM, Jeff Spaleta <[email-masked]>wrote:

> > On Wed, Jul 3, 2013 at 7:20 PM, Daniel Holbach <
> [email-masked]>
> > wrote:
> >>

---

From: Jono Bacon <[email-masked]>
Date: Thu, 11 Jul 2013 16:12:54 -0700

Thanks, Robert!

On Thu, Jul 11, 2013 at 3:04 PM, Robert Ancell
<[email-masked]>wrote:

> http://unity.ubuntu.com/mir/building_source_for_pc.html is now updated
> with more instructions.
>
>