Mir

Merge lp:~alan-griffiths/mir/a-simpler-server-setup into lp:mir

a-simpler-server-setup
Merge into development-branch

Proposed by Alan Griffiths on 2014-10-10

Status:	Merged
Approved by:	Alan Griffiths on 2014-10-15
Approved revision:	no longer in the source branch.
Merged at revision:	1984
Proposed branch:	lp:~alan-griffiths/mir/a-simpler-server-setup
Merge into:	lp:mir
Diff against target:	713 lines (+630/-0) 5 files modified include/server/mir/server.h (+217/-0) server-ABI-sha1sums (+1/-0) src/server/CMakeLists.txt (+1/-0) src/server/server.cpp (+373/-0) src/server/symbols.map (+38/-0)
To merge this branch:	bzr merge lp:~alan-griffiths/mir/a-simpler-server-setup
Related bugs:	Link a bug report

Reviewer	Review Type	Date Requested	Status
Kevin DuBois (community)			Approve on 2014-10-15
PS Jenkins bot (community)	continuous-integration		Approve on 2014-10-15
Alexandros Frantzis (community)		2014-10-10	Approve on 2014-10-15
Cemil Azizoglu (community)			Needs Fixing on 2014-10-14
Andreas Pokorny (community)			Approve on 2014-10-14
Review via email: mp+237990@code.launchpad.net

Commit message

mir: A simpler to use (and easier to maintain) way to customise and run a Mir server

Description of the change

mir: A simpler to use (and easier to maintain) way to customise and run a Mir server

The idea is to provide a declarative API for setting up the server that doesn't tie the client code into DefautServerConfiguration or another equally volatile interface.

Functions can be added to mir::Server without breaking backward API as they are non-virtual.

If clients are able to use an interface like this we can move DefaultServerConfiguration (and a bunch of other stuff) out of the public API/ABI.

This is extracted from lp:~alan-griffiths/mir/spike-a-simpler-server-setup/+merge/237625 by dropping the experimental changes to examples used as a proof-of-concept.

I'd like to land this and then work through the examples and acceptance tests to ensure they are implementable in terms of this interface. (Doing this as a single MP would be hard to review.)

NOTE: there is an alternative proposal, please consider both approaches when voting:

https://code.launchpad.net/~andreas-pokorny/mir/abi-stable-server-configuration-with-type_info/+merge/238144

Revision history for this message

PS Jenkins bot (ps-jenkins) wrote on 2014-10-10:

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/mir-ci/1788/rebuild

review: Approve (continuous-integration)

Revision history for this message

PS Jenkins bot (ps-jenkins) wrote on 2014-10-10:

FAILED: Continuous integration, rev:1973
http://jenkins.qa.ubuntu.com/job/mir-ci/1790/
Executed test runs:
    FAILURE: http://jenkins.qa.ubuntu.com/job/mir-android-utopic-i386-build/2091/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/mir-clang-utopic-amd64-build/2098/console
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-utopic-touch/2027
    FAILURE: http://jenkins.qa.ubuntu.com/job/mir-utopic-amd64-ci/128/console
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-builder-utopic-armhf/964
        deb: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-builder-utopic-armhf/964/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-runner-mako/3035
    SUCCESS: http://s-jenkins.ubuntu-ci:8080/job/touch-flash-device/14541

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/mir-ci/1790/rebuild

review: Needs Fixing (continuous-integration)

Revision history for this message

PS Jenkins bot (ps-jenkins) wrote on 2014-10-11:

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/mir-ci/1792/rebuild

review: Needs Fixing (continuous-integration)

Revision history for this message

Alan Griffiths (alan-griffiths) wrote on 2014-10-13:

Rebuilding (third time lucky?)

Revision history for this message

PS Jenkins bot (ps-jenkins) wrote on 2014-10-13:

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/mir-ci/1798/rebuild

review: Needs Fixing (continuous-integration)

Revision history for this message

PS Jenkins bot (ps-jenkins) wrote on 2014-10-13:

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/mir-ci/1799/rebuild

review: Needs Fixing (continuous-integration)

Revision history for this message

Alexandros Frantzis (afrantzis) wrote on 2014-10-13:

65 +

Extra blank line.

219 + bool exit_status{false};
220 + std::weak_ptr<options::Option> options;
222 + ServerConfiguration* server_config{nullptr};

Since ABI break protection is a major concern, we should hide all of these in 'Self'.

Nit (non-blocking):

227 +class detail::ServerAddConfigurationOptions

As mentioned in the past, I am not fond of this mechanism, but if people find it more convenient...

review: Needs Fixing

Revision history for this message

PS Jenkins bot (ps-jenkins) wrote on 2014-10-13:

FAILED: Continuous integration, rev:1975
http://jenkins.qa.ubuntu.com/job/mir-ci/1802/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-android-utopic-i386-build/2107
    FAILURE: http://jenkins.qa.ubuntu.com/job/mir-clang-utopic-amd64-build/2114/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-utopic-touch/2043/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/mir-utopic-amd64-ci/140/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-builder-utopic-armhf/980/console

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/mir-ci/1802/rebuild

review: Needs Fixing (continuous-integration)

Revision history for this message

Andreas Pokorny (andreas-pokorny) wrote on 2014-10-13:

the header checksums contain additional files probably left overs from merges?

review: Needs Fixing

Revision history for this message

PS Jenkins bot (ps-jenkins) wrote on 2014-10-13:

FAILED: Continuous integration, rev:1976
http://jenkins.qa.ubuntu.com/job/mir-ci/1807/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-android-utopic-i386-build/2114
    FAILURE: http://jenkins.qa.ubuntu.com/job/mir-clang-utopic-amd64-build/2121/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-utopic-touch/2050/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/mir-utopic-amd64-ci/145/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-builder-utopic-armhf/987/console

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/mir-ci/1807/rebuild

review: Needs Fixing (continuous-integration)

Revision history for this message

PS Jenkins bot (ps-jenkins) wrote on 2014-10-13:

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/mir-ci/1808/rebuild

review: Approve (continuous-integration)

Revision history for this message

Daniel van Vugt (vanvugt) wrote on 2014-10-14:

Oh, a Server class like I've been asking for for almost two years :D

Revision history for this message

PS Jenkins bot (ps-jenkins) wrote on 2014-10-14:

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/mir-ci/1815/rebuild

review: Approve (continuous-integration)

Revision history for this message

Alexandros Frantzis (afrantzis) wrote on 2014-10-14:

218 + struct ServerConfiguration;

Do we need this?

513 + self->server_config = nullptr;

Indentation (tab instead of spaces)

523 + std::cerr << "DEBUG: " << __PRETTY_FUNCTION__ << std::endl;

Not needed.

review: Needs Fixing

Revision history for this message

Andreas Pokorny (andreas-pokorny) wrote on 2014-10-14:

Two more things:

Whats the thought behind writing {*this} instead of just *this?
I think:

523 + std::cerr << "DEBUG: " << __PRETTY_FUNCTION__ << std::endl;

and iostream is not needed anymore?

Revision history for this message

Alan Griffiths (alan-griffiths) wrote on 2014-10-14:

> Two more things:
>
> Whats the thought behind writing {*this} instead of just *this?

We're constructing a helper object (which as the constructor isn't tagged explicit could be done the way you suggest).

> I think:
>
> 523 + std::cerr << "DEBUG: " << __PRETTY_FUNCTION__ << std::endl;

Done

> and iostream is not needed anymore?

std::cerr is used: "mir::report_exception(std::cerr);"

Revision history for this message

Andreas Pokorny (andreas-pokorny) wrote on 2014-10-14:

> > Two more things:
> >
> > Whats the thought behind writing {*this} instead of just *this?
>
> We're constructing a helper object (which as the constructor isn't tagged
> explicit could be done the way you suggest).

ok, my gcc didnt complain about - maybe clang would.

Revision history for this message

Andreas Pokorny (andreas-pokorny) wrote on 2014-10-14:

> > > Two more things:
> > >
> > > Whats the thought behind writing {*this} instead of just *this?
> >
> > We're constructing a helper object (which as the constructor isn't tagged
> > explicit could be done the way you suggest).
>
> ok, my gcc didnt complain about - maybe clang would.

misunderstood what you just said. interesting syntax idea to indicate the conversion in the return statement.

review: Approve

Revision history for this message

Kevin DuBois (kdub) wrote on 2014-10-14:

So I guess I favor this MP over the alternative, mostly because this one is more straightforward to reason (from a user's perspective) about what is available for use.

In light of the proposed plan, the following is more of a comment; but I'm concerned that we're exposing too much of our internal composition scheduling with the functions that remain exposed. (It would be good for mir's ease-of-use to be able to reuse MultiThreadedCompositor)

nits:
#1
31 +namespace compositor{ class Compositor; }
spacing

#2
148 + /// \return the graphics display options.
151 + /// \return the graphics platform options.
In light of the other mentions of 'options' in this header, we should drop 'options' off the end of these comments

#3
detail::ServerAddConfigurationOptions
AdditionalConfigurationOptions or NonstandardConfigurationOptions seems like a stronger name.

#4
OptionType::null seems more like OptionType::bool to me.

review: Needs Fixing

Revision history for this message

Alexandros Frantzis (afrantzis) wrote on 2014-10-14:

> 218 + struct ServerConfiguration;
> Do we need this?

What I meant was: do we need for this to be a private mir::Server struct instead of a only a struct inside server.cpp ? Doesn't affect ABI either way, but there is no point exposing the type at all either.

208 + void override_the_surface_configurator(std::function<std::shared_ptr<scene::SurfaceConfigurator>()> const& surface_configurator_builder);
209 +
210 + /// Sets a wrapper functor for creating the session coordinator.
211 + void wrap_session_coordinator(std::function<std::shared_ptr<scene::SessionCoordinator>(std::shared_ptr<scene::SessionCoordinator> const& wrapped)> const& wrapper);

Lines are too long and there is too much repetition, so I think the code would benefit from function types for the parameters, e.g.:

template<typename T> using Builder = std::function<std::shared_ptr<T>()>;
template<typename T> using Wrapper = std::function<std::shared_ptr<T>(std::shared_ptr<T> const&)>;

review: Needs Fixing

Revision history for this message

Alan Griffiths (alan-griffiths) wrote on 2014-10-14:

> #3
> detail::ServerAddConfigurationOptions
> AdditionalConfigurationOptions or NonstandardConfigurationOptions seems like a
> stronger name.

Or I could just drop the chaining functionality this supports.

Any opinions? (I know Alexandros would drop it>)

> #4
> OptionType::null seems more like OptionType::bool to me.

Not so. This is a flag that exists or not, not one that takes [true|false]

Revision history for this message

PS Jenkins bot (ps-jenkins) wrote on 2014-10-14:

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/mir-ci/1818/rebuild

review: Approve (continuous-integration)

Revision history for this message

Alan Griffiths (alan-griffiths) wrote on 2014-10-14:

> > 218 + struct ServerConfiguration;
> > Do we need this?
>
> What I meant was: do we need for this to be a private mir::Server struct
> instead of a only a struct inside server.cpp ? Doesn't affect ABI either way,
> but there is no point exposing the type at all either.

It isn't obvious, but either Self needs to be a public type or there needs to be a way of giving ServerConfiguration access to it.

> 208 + void override_the_surface_configurator(std::function<std::shared_ptr
> <scene::SurfaceConfigurator>()> const& surface_configurator_builder);
> 209 +
> 210 + /// Sets a wrapper functor for creating the session coordinator.
> 211 + void wrap_session_coordinator(std::function<std::shared_ptr<scene::S
> essionCoordinator>(std::shared_ptr<scene::SessionCoordinator> const& wrapped)>
> const& wrapper);
>
> Lines are too long and there is too much repetition, so I think the code would
> benefit from function types for the parameters, e.g.:
>
> template<typename T> using Builder = std::function<std::shared_ptr<T>()>;
> template<typename T> using Wrapper =
> std::function<std::shared_ptr<T>(std::shared_ptr<T> const&)>;

This would make the declarations more concise.

But it makes it harder for the user see the type they need to supply as a parameter.

Revision history for this message

Alan Griffiths (alan-griffiths) wrote on 2014-10-14:

> nits:
> #1
> 31 +namespace compositor{ class Compositor; }
> spacing
>
> #2
> 148 + /// \return the graphics display options.
> 151 + /// \return the graphics platform options.
> In light of the other mentions of 'options' in this header, we should drop
> 'options' off the end of these comments

fixed

Revision history for this message

Cemil Azizoglu (cemil-azizoglu) wrote on 2014-10-14:

1. Should we reserve a buffer zone after accessors, overrides, and wrappers for future expansion? Otherwise we'll likely have interleaved accessors/overrides/wrappers areas.

2. No tests?

3.
s/hander/handler
111 + /// If set_command_line_hander is not called the default action is to exit by
114 + void set_command_line_hander(
115 + std::function<void(int argc, char const* const* argv)> const& command_line_hander);
365 + std::function<void(int argc, char const* const* argv)> command_line_hander{};
439 + std::function<void(int argc, char const* const* argv)> const& command_line_hander)
441 + if (command_line_hander)
442 + return std::make_shared<mo::DefaultConfiguration>(argc, argv, command_line_hander);
493 + auto const options = configuration_options(self->argc, self->argv, self->command_line_hander);
701 + mir::Server::set_command_line_hander*;

4.
s/add/Add
s/an/a
125 + /// add an callback to be invoked when the server has been initialized,

5.
s/set/Set
107 + /// set a handler for any command line options Mir does not recognise.

6.
66 + * These are the commands used to start and stop.
Based on this comment, to be consistent, should 'run' be named 'start'?
71 + /// Run the Mir server until it exits
72 + void run();

review: Needs Fixing

Revision history for this message

PS Jenkins bot (ps-jenkins) wrote on 2014-10-14:

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/mir-ci/1819/rebuild

review: Approve (continuous-integration)

Revision history for this message

Alexandros Frantzis (afrantzis) wrote on 2014-10-15:

> It isn't obvious, but either Self needs to be a public type or there needs to be a
> way of giving ServerConfiguration access to it.

Ah, indeed.

> This would make the declarations more concise.
> But it makes it harder for the user see the type they need to supply as a parameter.

Perhaps the first couple times the user will have to look up the type definition (which isn't hard since it will be in the same code block). But subsequently the user will read, e.g., "WrapperFunction<Type>" and just know what's expected, instead of having to mentally reparse the long parameter type every time.

Revision history for this message

Alan Griffiths (alan-griffiths) wrote on 2014-10-15:

> 1. Should we reserve a buffer zone after accessors, overrides, and wrappers
> for future expansion? Otherwise we'll likely have interleaved
> accessors/overrides/wrappers areas.

A buffer zone where? These are non-virtual functions.

> 2. No tests?

True. If you can think of an effective way to test that the system gets configured & run correctly then I'd be delighted to add them.

In practice, this will get exercised properly when the acceptance tests get migrated to this interface. (Which is on my TODO list.)

> 3.
> s/hander/handler
> 111 + /// If set_command_line_hander is not called the default action
> is to exit by
> 114 + void set_command_line_hander(
> 115 + std::function<void(int argc, char const* const* argv)> const&
> command_line_hander);
> 365 + std::function<void(int argc, char const* const* argv)>
> command_line_hander{};
> 439 + std::function<void(int argc, char const* const* argv)> const&
> command_line_hander)
> 441 + if (command_line_hander)
> 442 + return std::make_shared<mo::DefaultConfiguration>(argc, argv,
> command_line_hander);
> 493 + auto const options = configuration_options(self->argc,
> self->argv, self->command_line_hander);
> 701 + mir::Server::set_command_line_hander*;

Fixed

> 4.
> s/add/Add
> s/an/a
> 125 + /// add an callback to be invoked when the server has been
> initialized,

Fixed

> 5.
> s/set/Set
> 107 + /// set a handler for any command line options Mir does not
> recognise.

Fixed.

> 6.
> 66 + * These are the commands used to start and stop.
> Based on this comment, to be consistent, should 'run' be named 'start'?
> 71 + /// Run the Mir server until it exits
> 72 + void run();

Revision history for this message

Alan Griffiths (alan-griffiths) wrote on 2014-10-15:

> > This would make the declarations more concise.
> > But it makes it harder for the user see the type they need to supply as a
> parameter.
>
> Perhaps the first couple times the user will have to look up the type
> definition (which isn't hard since it will be in the same code block). But
> subsequently the user will read, e.g., "WrapperFunction<Type>" and just know
> what's expected, instead of having to mentally reparse the long parameter type
> every time.

The first couple of times are the "barrier to entry" - after that it doesn't matter which way we write them as the user knows what to expect and doesn't read the parameter type.

It is *very* important to make adopting Mir as easy as possible.

Practically, can we land with this spelling and I'll MP your suggestion on top of that for discussion? (It isn't an API/ABI change.)

Revision history for this message

Alan Griffiths (alan-griffiths) wrote on 2014-10-15:

> 227 +class detail::ServerAddConfigurationOptions
>
> As mentioned in the past, I am not fond of this mechanism, but if people find
> it more convenient...

dropped

Revision history for this message

Alexandros Frantzis (afrantzis) wrote on 2014-10-15:

> The first couple of times are the "barrier to entry" - after that it doesn't matter
> which way we write them as the user knows what to expect and doesn't read the parameter type.

We may be consistent, but we should make this explicit and easily discoverable. Users can't really be sure that the signature is the same without re-reading the (long and not easily parsable) parameter type.

> It is *very* important to make adopting Mir as easy as possible.

I doubt that this is a barrier to adoption. If we think that target developers can't bother to find a definition in the same code block they are currently looking at, then we should surely get rid of "detail::ServerAddConfigurationOptions" and "auto get_options() const -> std::shared_ptr<options::Option>" and "enum class OptionType"...

> Practically, can we land with this spelling and I'll MP your suggestion on

No problem.

review: Approve

Revision history for this message

PS Jenkins bot (ps-jenkins) wrote on 2014-10-15:

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/mir-ci/1825/rebuild

review: Approve (continuous-integration)

Revision history for this message

PS Jenkins bot (ps-jenkins) wrote on 2014-10-15:

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/mir-ci/1827/rebuild

review: Approve (continuous-integration)

Revision history for this message

Kevin DuBois (kdub) wrote on 2014-10-15:

okay, looks good to me

review: Approve

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk

Subscribers

People subscribed via source and target branches

to all changes:

Alan Griffiths

Emanuele Antonio Faraone

Gerry Boland

Mir development team

 === added file 'include/server/mir/server.h'
 --- include/server/mir/server.h	1970-01-01 00:00:00 +0000
 +++ include/server/mir/server.h	2014-10-15 09:19:21 +0000
@@ -0,0 +1,217 @@
++/*
++ * Copyright © 2014 Canonical Ltd.
++ *
++ * This program is free software: you can redistribute it and/or modify it
++ * under the terms of the GNU General Public License version 3,
++ * as published by the Free Software Foundation.
++ *
++ * This program is distributed in the hope that it will be useful,
++ * but WITHOUT ANY WARRANTY; without even the implied warranty of
++ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
++ * GNU General Public License for more details.
++ *
++ * You should have received a copy of the GNU General Public License
++ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
++ *
++ * Authored By: Alan Griffiths <alan@octopull.co.uk>
++ */
++
++#ifndef MIR_SERVER_H_
++#define MIR_SERVER_H_
++
++#include <functional>
++#include <memory>
++
++namespace mir
++{
++namespace compositor { class Compositor; }
++namespace frontend { class SessionAuthorizer; }
++namespace graphics { class Platform; class Display; class GLConfig; }
++namespace input { class CompositeEventFilter; class InputDispatcher; class CursorListener; }
++namespace options { class Option; }
++namespace shell { class FocusSetter; class DisplayLayout; }
++namespace scene
++{
++class PlacementStrategy;
++class SessionListener;
++class PromptSessionListener;
++class SurfaceConfigurator;
++class SessionCoordinator;
++class SurfaceCoordinator;
++}
++
++class MainLoop;
++class ServerStatusListener;
++
++enum class OptionType
++{
++    null,
++    integer,
++    string
++};
++
++/// Customise and run a Mir server.
++class Server
++{
++public:
++    Server();
++
++/** @name Essential operations
++ * These are the commands used to run and stop.
++ *  @{ */
++    /// set the command line (this must remain valid while run() is called)
++    void set_command_line(int argc, char const* argv[]);
++
++    /// Run the Mir server until it exits
++    void run();
++
++    /// Tell the Mir server to exit
++    void stop();
++
++    /// returns true if and only if server exited normally. Otherwise false.
++    bool exited_normally();
++/** @} */
++
++/** @name Configuration options
++ *  @{ */
++    /// Add user configuration option(s) to Mir's option handling.
++    /// These will be resolved during initialisation from the command line,
++    /// environment variables, a config file or the supplied default.
++    void add_configuration_option(
++        std::string const& option,
++        std::string const& description,
++        int default_value);
++
++    /// Add user configuration option(s) to Mir's option handling.
++    /// These will be resolved during initialisation from the command line,
++    /// environment variables, a config file or the supplied default.
++    void add_configuration_option(
++        std::string const& option,
++        std::string const& description,
++        std::string const& default_value);
++
++    /// Add user configuration option(s) to Mir's option handling.
++    /// These will be resolved during initialisation from the command line,
++    /// environment variables, a config file or the supplied default.
++    void add_configuration_option(
++        std::string const& option,
++        std::string const& description,
++        OptionType type);
++
++    /// Set a handler for any command line options Mir does not recognise.
++    /// This will be invoked if any unrecognised options are found during initialisation.
++    /// Any unrecognised arguments are passed to this function. The pointers remain valid
++    /// for the duration of the call only.
++    /// If set_command_line_handler is not called the default action is to exit by
++    /// throwing mir::AbnormalExit (which will be handled by the exception handler prior to
++    /// exiting run().
++    void set_command_line_handler(
++        std::function<void(int argc, char const* const* argv)> const& command_line_hander);
++
++    /// Returns the configuration options.
++    /// This will be null before initialization completes. It will be available
++    /// when the init_callback has been invoked (and thereafter until the server exits).
++    auto get_options() const -> std::shared_ptr<options::Option>;
++/** @} */
++
++/** @name Using hooks into the run() logic
++ *  @{ */
++    /// Add a callback to be invoked when the server has been initialized,
++    /// but before it starts. This allows client code to get access Mir objects.
++    /// If multiple callbacks are added they will be invoked in the sequence added.
++    void add_init_callback(std::function<void()> const& init_callback);
++
++    /// Set a handler for exceptions. This is invoked in a catch (...) block and
++    /// the exception can be re-thrown to retrieve type information.
++    /// The default action is to call mir::report_exception(std::cerr)
++    void set_exception_handler(std::function<void()> const& exception_handler);
++/** @} */
++
++/** @name Getting access to Mir subsystems
++ * These will throw before initialization starts or after the server exits.
++ * They may be invoked by the functors that provide alternative implementations of
++ * Mir subsystems and when the init_callback is invoked (and thereafter
++ * until the server exits).
++ *  @{ */
++    /// \return the composite event filter.
++    auto the_composite_event_filter() const -> std::shared_ptr<input::CompositeEventFilter>;
++
++    /// \return the cursor listener.
++    auto the_cursor_listener() const -> std::shared_ptr<input::CursorListener>;
++
++    /// \return the graphics display.
++    auto the_display() const -> std::shared_ptr<graphics::Display>;
++
++    /// \return the graphics platform.
++    auto the_graphics_platform() const -> std::shared_ptr<graphics::Platform>;
++
++    /// \return the main loop.
++    auto the_main_loop() const -> std::shared_ptr<MainLoop>;
++
++    /// \return the prompt session listener.
++    auto the_prompt_session_listener() const -> std::shared_ptr<scene::PromptSessionListener>;
++
++    /// \return the session authorizer.
++    auto the_session_authorizer() const -> std::shared_ptr<frontend::SessionAuthorizer>;
++
++    /// \return the session listener.
++    auto the_session_listener() const -> std::shared_ptr<scene::SessionListener>;
++
++    /// \return the display layout.
++    auto the_shell_display_layout() const -> std::shared_ptr<shell::DisplayLayout>;
++
++    /// \return the surface configurator.
++    auto the_surface_configurator() const -> std::shared_ptr<scene::SurfaceConfigurator>;
++/** @} */
++
++/** @name Providing custom implementation
++ * Provide alternative implementations of Mir subsystems: the functors will be invoked during initialization
++ * (this is only useful before initialization starts).
++ *  @{ */
++    /// Sets an override functor for creating the compositor.
++    void override_the_compositor(std::function<std::shared_ptr<compositor::Compositor>()> const& compositor_builder);
++
++    /// Sets an override functor for creating the cursor listener.
++    void override_the_cursor_listener(std::function<std::shared_ptr<input::CursorListener>()> const& cursor_listener_builder);
++
++    /// Sets an override functor for creating the gl config.
++    void override_the_gl_config(std::function<std::shared_ptr<graphics::GLConfig>()> const& gl_config_builder);
++
++    /// Sets an override functor for creating the input dispatcher.
++    void override_the_input_dispatcher(std::function<std::shared_ptr<input::InputDispatcher>()> const& input_dispatcher_builder);
++
++    /// Sets an override functor for creating the placement strategy.
++    void override_the_placement_strategy(std::function<std::shared_ptr<scene::PlacementStrategy>()> const& placement_strategy_builder);
++
++    /// Sets an override functor for creating the prompt session listener.
++    void override_the_prompt_session_listener(std::function<std::shared_ptr<scene::PromptSessionListener>()> const& prompt_session_listener_builder);
++
++    /// Sets an override functor for creating the status listener.
++    void override_the_server_status_listener(std::function<std::shared_ptr<ServerStatusListener>()> const& server_status_listener_builder);
++
++    /// Sets an override functor for creating the session authorizer.
++    void override_the_session_authorizer(std::function<std::shared_ptr<frontend::SessionAuthorizer>()> const& session_authorizer_builder);
++
++    /// Sets an override functor for creating the session listener.
++    void override_the_session_listener(std::function<std::shared_ptr<scene::SessionListener>()> const& session_listener_builder);
++
++    /// Sets an override functor for creating the shell focus setter.
++    void override_the_shell_focus_setter(std::function<std::shared_ptr<shell::FocusSetter>()> const& focus_setter_builder);
++
++    /// Sets an override functor for creating the surface configurator.
++    void override_the_surface_configurator(std::function<std::shared_ptr<scene::SurfaceConfigurator>()> const& surface_configurator_builder);
++
++    /// Sets a wrapper functor for creating the session coordinator.
++    void wrap_session_coordinator(std::function<std::shared_ptr<scene::SessionCoordinator>(std::shared_ptr<scene::SessionCoordinator> const& wrapped)> const& wrapper);
++
++    /// Sets a wrapper functor for creating the surface coordinator.
++    void wrap_surface_coordinator(std::function<std::shared_ptr<scene::SurfaceCoordinator>(std::shared_ptr<scene::SurfaceCoordinator> const& wrapped)> const& wrapper);
++/** @} */
++
++private:
++    struct ServerConfiguration;
++    struct Self;
++    std::shared_ptr<Self> const self;
++};
++}
++#endif /* SERVER_H_ */
 === modified file 'server-ABI-sha1sums'
 --- server-ABI-sha1sums	2014-10-14 17:55:14 +0000
 +++ server-ABI-sha1sums	2014-10-15 09:19:21 +0000
@@ -95,6 +95,7 @@
 e9f458ffc4288d304413f3fa0b1dcc95a093d  include/server/mir/scene/surface_observer.h
 ef3e99901168cda296d74d05a979f47bf9c3ff1  include/server/mir/server_action_queue.h
 d83a51c278b8b71866d2178d9b6387c1f91a7d0  include/server/mir/server_configuration.h
++5d79d4a973b597d7cc1de766bd0ef3d30b389e18  include/server/mir/server.h
 b500339bfccd07a9bed8298f75a68b18f5c  include/server/mir/server_status_listener.h
 c04f32b60e680140148dc9dc2295de145b9c1  include/server/mir/shell/display_layout.h
 a2107b01feae13060d5c305804906e53c52e0be  include/server/mir/shell/focus_controller.h
 === modified file 'src/server/CMakeLists.txt'
 --- src/server/CMakeLists.txt	2014-10-10 05:44:12 +0000
 +++ src/server/CMakeLists.txt	2014-10-15 09:19:21 +0000
@@ -32,6 +32,7 @@
    default_server_configuration.cpp
    asio_main_loop.cpp
    default_emergency_cleanup.cpp
++  server.cpp
+ )
  set(MIR_SERVER_OBJECTS
 === added file 'src/server/server.cpp'
 --- src/server/server.cpp	1970-01-01 00:00:00 +0000
 +++ src/server/server.cpp	2014-10-15 09:19:21 +0000
@@ -0,0 +1,373 @@
++/*
++ * Copyright © 2014 Canonical Ltd.
++ *
++ * This program is free software: you can redistribute it and/or modify it
++ * under the terms of the GNU General Public License version 3,
++ * as published by the Free Software Foundation.
++ *
++ * This program is distributed in the hope that it will be useful,
++ * but WITHOUT ANY WARRANTY; without even the implied warranty of
++ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
++ * GNU General Public License for more details.
++ *
++ * You should have received a copy of the GNU General Public License
++ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
++ *
++ * Authored By: Alan Griffiths <alan@octopull.co.uk>
++ */
++
++#include "mir/server.h"
++
++#include "mir/options/default_configuration.h"
++#include "mir/default_server_configuration.h"
++#include "mir/main_loop.h"
++#include "mir/report_exception.h"
++#include "mir/run_mir.h"
++
++#include <iostream>
++
++namespace mo = mir::options;
++
++#define FOREACH_WRAPPER(MACRO)\
++    MACRO(session_coordinator)\
++    MACRO(surface_coordinator)
++
++#define FOREACH_OVERRIDE(MACRO)\
++    MACRO(compositor)\
++    MACRO(cursor_listener)\
++    MACRO(gl_config)\
++    MACRO(input_dispatcher)\
++    MACRO(placement_strategy)\
++    MACRO(prompt_session_listener)\
++    MACRO(server_status_listener)\
++    MACRO(session_authorizer)\
++    MACRO(session_listener)\
++    MACRO(shell_focus_setter)\
++    MACRO(surface_configurator)
++
++#define FOREACH_ACCESSOR(MACRO)\
++    MACRO(the_composite_event_filter)\
++    MACRO(the_display)\
++    MACRO(the_graphics_platform)\
++    MACRO(the_main_loop)\
++    MACRO(the_prompt_session_listener)\
++    MACRO(the_session_authorizer)\
++    MACRO(the_session_listener)\
++    MACRO(the_shell_display_layout)\
++    MACRO(the_surface_configurator)
++
++#define MIR_SERVER_BUILDER(name)\
++    std::function<std::result_of<decltype(&mir::DefaultServerConfiguration::the_##name)(mir::DefaultServerConfiguration*)>::type()> name##_builder;
++
++#define MIR_SERVER_WRAPPER(name)\
++    std::function<std::result_of<decltype(&mir::DefaultServerConfiguration::the_##name)(mir::DefaultServerConfiguration*)>::type\
++        (std::result_of<decltype(&mir::DefaultServerConfiguration::the_##name)(mir::DefaultServerConfiguration*)>::type const&)> name##_wrapper;
++
++struct mir::Server::Self
++{
++    bool exit_status{false};
++    std::weak_ptr<options::Option> options;
++    ServerConfiguration* server_config{nullptr};
++
++    std::function<void()> init_callback{[]{}};
++    int argc{0};
++    char const** argv{nullptr};
++    std::function<void()> exception_handler{};
++
++    std::function<void(int argc, char const* const* argv)> command_line_hander{};
++
++    /// set a callback to introduce additional configuration options.
++    /// this will be invoked by run() before server initialisation starts
++    void set_add_configuration_options(
++        std::function<void(options::DefaultConfiguration& config)> const& add_configuration_options);
++
++    std::function<void(options::DefaultConfiguration& config)> add_configuration_options{
++        [](options::DefaultConfiguration&){}};
++
++    FOREACH_OVERRIDE(MIR_SERVER_BUILDER)
++
++    FOREACH_WRAPPER(MIR_SERVER_WRAPPER)
++};
++
++#undef MIR_SERVER_BUILDER
++#undef MIR_SERVER_WRAPPER
++
++#define MIR_SERVER_CONFIG_OVERRIDE(name)\
++auto the_##name()\
++-> decltype(mir::DefaultServerConfiguration::the_##name()) override\
++{\
++    if (self->name##_builder)\
++        return name(\
++            [this] { return self->name##_builder(); });\
++\
++    return mir::DefaultServerConfiguration::the_##name();\
++}
++
++#define MIR_SERVER_CONFIG_WRAP(name)\
++auto wrap_##name(decltype(Self::name##_wrapper)::result_type const& wrapped)\
++-> decltype(mir::DefaultServerConfiguration::wrap_##name({})) override\
++{\
++    if (self->name##_wrapper)\
++        return name(\
++            [&] { return self->name##_wrapper(wrapped); });\
++\
++    return mir::DefaultServerConfiguration::wrap_##name(wrapped);\
++}
++
++struct mir::Server::ServerConfiguration : mir::DefaultServerConfiguration
++{
++    ServerConfiguration(
++        std::shared_ptr<options::Configuration> const& configuration_options,
++        std::shared_ptr<Self> const self) :
++        DefaultServerConfiguration(configuration_options),
++        self(self)
++    {
++    }
++
++    using mir::DefaultServerConfiguration::the_options;
++
++    // TODO the MIR_SERVER_CONFIG_OVERRIDE macro expects a CachePtr named
++    // TODO "placement_strategy" not "shell_placement_strategy".
++    // Unfortunately, "shell_placement_strategy" is currently part of our
++    // published API and used by qtmir: we cannot just rename it to remove
++    // this ugliness. (Yet.)
++    decltype(shell_placement_strategy)& placement_strategy = shell_placement_strategy;
++
++    FOREACH_OVERRIDE(MIR_SERVER_CONFIG_OVERRIDE)
++
++    FOREACH_WRAPPER(MIR_SERVER_CONFIG_WRAP)
++
++    std::shared_ptr<Self> const self;
++};
++
++#undef MIR_SERVER_CONFIG_OVERRIDE
++#undef MIR_SERVER_CONFIG_WRAP
++
++namespace
++{
++std::shared_ptr<mo::DefaultConfiguration> configuration_options(
++    int argc,
++    char const** argv,
++    std::function<void(int argc, char const* const* argv)> const& command_line_hander)
++{
++    if (command_line_hander)
++        return std::make_shared<mo::DefaultConfiguration>(argc, argv, command_line_hander);
++    else
++        return std::make_shared<mo::DefaultConfiguration>(argc, argv);
++
++}
++}
++
++mir::Server::Server() :
++    self(std::make_shared<Self>())
++{
++}
++
++void mir::Server::Self::set_add_configuration_options(
++    std::function<void(mo::DefaultConfiguration& config)> const& add_configuration_options)
++{
++    this->add_configuration_options = add_configuration_options;
++}
++
++
++void mir::Server::set_command_line(int argc, char const* argv[])
++{
++    self->argc = argc;
++    self->argv = argv;
++}
++
++void mir::Server::add_init_callback(std::function<void()> const& init_callback)
++{
++    auto const& existing = self->init_callback;
++
++    auto const updated = [=]
++        {
++            existing();
++            init_callback();
++        };
++
++    self->init_callback = updated;
++}
++
++auto mir::Server::get_options() const -> std::shared_ptr<options::Option>
++{
++    return self->options.lock();
++}
++
++void mir::Server::set_exception_handler(std::function<void()> const& exception_handler)
++{
++    self->exception_handler = exception_handler;
++}
++
++void mir::Server::run()
++try
++{
++    auto const options = configuration_options(self->argc, self->argv, self->command_line_hander);
++
++    self->add_configuration_options(*options);
++
++    ServerConfiguration config{options, self};
++
++    self->server_config = &config;
++
++    self->options = config.the_options();
++
++    run_mir(config, [&](DisplayServer&)
++        {
++            self->init_callback();
++        });
++
++    self->exit_status = true;
++    self->server_config = nullptr;
++}
++catch (...)
++{
++    self->server_config = nullptr;
++
++    if (self->exception_handler)
++        self->exception_handler();
++    else
++        mir::report_exception(std::cerr);
++}
++
++void mir::Server::stop()
++{
++    if (auto const main_loop = the_main_loop())
++        main_loop->stop();
++}
++
++bool mir::Server::exited_normally()
++{
++    return self->exit_status;
++}
++
++namespace
++{
++auto const no_config_to_access = "Cannot access config when no config active.";
++}
++
++#define MIR_SERVER_ACCESSOR(name)\
++auto mir::Server::name() const -> decltype(self->server_config->name())\
++{\
++    if (self->server_config) return self->server_config->name();\
++    BOOST_THROW_EXCEPTION(std::logic_error(no_config_to_access));\
++}
++
++FOREACH_ACCESSOR(MIR_SERVER_ACCESSOR)
++
++#undef MIR_SERVER_ACCESSOR
++
++#define MIR_SERVER_OVERRIDE(name)\
++void mir::Server::override_the_##name(decltype(Self::name##_builder) const& value)\
++{\
++    self->name##_builder = value;\
++}
++
++FOREACH_OVERRIDE(MIR_SERVER_OVERRIDE)
++
++#undef MIR_SERVER_OVERRIDE
++
++#define MIR_SERVER_WRAP(name)\
++void mir::Server::wrap_##name(decltype(Self::name##_wrapper) const& value)\
++{\
++    self->name##_wrapper = value;\
++}
++
++FOREACH_WRAPPER(MIR_SERVER_WRAP)
++
++#undef MIR_SERVER_WRAP
++
++void mir::Server::add_configuration_option(
++    std::string const& option,
++    std::string const& description,
++    int default_)
++{
++    namespace po = boost::program_options;
++
++    auto const& existing = self->add_configuration_options;
++
++    auto const option_adder = [=](options::DefaultConfiguration& config)
++        {
++            existing(config);
++
++            config.add_options()
++            (option.c_str(), po::value<int>()->default_value(default_), description.c_str());
++        };
++
++    self->set_add_configuration_options(option_adder);
++}
++
++void mir::Server::add_configuration_option(
++    std::string const& option,
++    std::string const& description,
++    std::string const& default_)
++{
++    namespace po = boost::program_options;
++
++    auto const& existing = self->add_configuration_options;
++
++    auto const option_adder = [=](options::DefaultConfiguration& config)
++        {
++            existing(config);
++
++            config.add_options()
++            (option.c_str(), po::value<std::string>()->default_value(default_), description.c_str());
++        };
++
++    self->set_add_configuration_options(option_adder);
++}
++
++void mir::Server::add_configuration_option(
++    std::string const& option,
++    std::string const& description,
++    OptionType type)
++{
++    namespace po = boost::program_options;
++
++    auto const& existing = self->add_configuration_options;
++
++    switch (type)
++    {
++    case OptionType::null:
++        {
++            auto const option_adder = [=](options::DefaultConfiguration& config)
++                {
++                    existing(config);
++
++                    config.add_options()
++                    (option.c_str(), description.c_str());
++                };
++
++            self->set_add_configuration_options(option_adder);
++        }
++        break;
++
++    case OptionType::integer:
++        {
++            auto const option_adder = [=](options::DefaultConfiguration& config)
++                {
++                    existing(config);
++
++                    config.add_options()
++                    (option.c_str(), po::value<int>(), description.c_str());
++                };
++
++            self->set_add_configuration_options(option_adder);
++        }
++        break;
++
++    case OptionType::string:
++        {
++            auto const option_adder = [=](options::DefaultConfiguration& config)
++                {
++                    existing(config);
++
++                    config.add_options()
++                    (option.c_str(), po::value<std::string>(), description.c_str());
++                };
++
++            self->set_add_configuration_options(option_adder);
++        }
++        break;
++    }
++}
 === modified file 'src/server/symbols.map'
 --- src/server/symbols.map	2014-10-14 17:55:14 +0000
 +++ src/server/symbols.map	2014-10-15 09:19:21 +0000
@@ -375,6 +375,7 @@
      mir::ServerActionQueue::resume_processing_for*;
      mir::ServerActionQueue::?ServerActionQueue*;
      mir::ServerActionQueue::ServerActionQueue*;
++    mir::Server::add_configuration_option*;
      mir::ServerConfiguration::operator*;
      mir::ServerConfiguration::?ServerConfiguration*;
      mir::ServerConfiguration::ServerConfiguration*;
@@ -390,12 +391,45 @@
      mir::ServerConfiguration::the_main_loop*;
      mir::ServerConfiguration::the_prompt_connector*;
      mir::ServerConfiguration::the_server_status_listener*;
++    mir::Server::add_init_callback*;
++    mir::Server::exited_normally*;
++    mir::Server::get_options*;
++    mir::Server::override_the_compositor*;
++    mir::Server::override_the_cursor_listener*;
++    mir::Server::override_the_gl_config*;
++    mir::Server::override_the_input_dispatcher*;
++    mir::Server::override_the_placement_strategy*;
++    mir::Server::override_the_prompt_session_listener*;
++    mir::Server::override_the_server_status_listener*;
++    mir::Server::override_the_session_authorizer*;
++    mir::Server::override_the_session_listener*;
++    mir::Server::override_the_shell_focus_setter*;
++    mir::Server::override_the_surface_configurator*;
++    mir::Server::run*;
++    mir::Server::Server*;
++    mir::Server::set_command_line*;
++    mir::Server::set_command_line_hander*;
++    mir::Server::set_exception_handler*;
      mir::ServerStatusListener::operator*;
      mir::ServerStatusListener::paused*;
      mir::ServerStatusListener::resumed*;
      mir::ServerStatusListener::?ServerStatusListener*;
      mir::ServerStatusListener::ServerStatusListener*;
      mir::ServerStatusListener::started*;
++    mir::Server::stop*;
++    mir::Server::the_composite_event_filter*;
++    mir::Server::the_cursor_listener*;
++    mir::Server::the_display*;
++    mir::Server::the_graphics_platform*;
++    mir::Server::the_main_loop*;
++    mir::Server::the_prompt_session_listener*;
++    mir::Server::the_server_status_listener*;
++    mir::Server::the_session_authorizer*;
++    mir::Server::the_session_listener*;
++    mir::Server::the_shell_display_layout*;
++    mir::Server::the_surface_configurator*;
++    mir::Server::wrap_session_coordinator*;
++    mir::Server::wrap_surface_coordinator*;
      mir::shell::DisplayLayout::clip_to_output*;
      mir::shell::DisplayLayout::?DisplayLayout*;
      mir::shell::DisplayLayout::DisplayLayout*;
@@ -592,6 +626,7 @@
      typeinfo?for?mir::compositor::Scene;
      typeinfo?for?mir::compositor::SceneElement;
      typeinfo?for?mir::DefaultServerConfiguration;
++    typeinfo?for?mir::detail::ServerAddConfigurationOptions;
      typeinfo?for?mir::DisplayServer;
      typeinfo?for?mir::EmergencyCleanup;
      typeinfo?for?mir::frontend::DisplayChanger;
@@ -633,6 +668,7 @@
      typeinfo?for?mir::scene::SurfaceCoordinator;
      typeinfo?for?mir::scene::SurfaceCreationParameters;
      typeinfo?for?mir::scene::SurfaceObserver;
++    typeinfo?for?mir::Server;
      typeinfo?for?mir::ServerActionQueue;
      typeinfo?for?mir::ServerConfiguration;
      typeinfo?for?mir::ServerStatusListener;
@@ -649,6 +685,7 @@
      vtable?for?mir::compositor::Scene;
      vtable?for?mir::compositor::SceneElement;
      vtable?for?mir::DefaultServerConfiguration;
++    vtable?for?mir::detail::ServerAddConfigurationOptions;
      vtable?for?mir::DisplayServer;
      vtable?for?mir::EmergencyCleanup;
      vtable?for?mir::frontend::DisplayChanger;
@@ -690,6 +727,7 @@
      vtable?for?mir::scene::SurfaceCoordinator;
      vtable?for?mir::scene::SurfaceCreationParameters;
      vtable?for?mir::scene::SurfaceObserver;
++    vtable?for?mir::Server;
      vtable?for?mir::ServerActionQueue;
      vtable?for?mir::ServerConfiguration;
      vtable?for?mir::ServerStatusListener;