Patch for Bug #227013 - /boot not mounted

[moblin-image-creator.eeepc.git] / README

Introduction
------------

Moblin-Image-Creator, or Image-Creator for short, is a tool aimed at
making life easier for the mobile and embedded developer.  The tools
is designed to be extremely flexible with platform specific knowledge
isolated to a platform definition.  Initial focus is on a new class of
devices known as Mobile Internet Devices (MID's), but the design of
image-creator is not MID specific and talk is already in progress to
add new platform definitions to build Consumer Electronics stacks such
as TV set-top boxes.

There are three fundamental features that image-creator provides:
* creation of a platform specific build environment
* creation of platform specific target file-systems
* providing user selectable "feature sets" (or fsets) to install 
  bundles of packages that provide some high-level functionality

In addition to this there are many other smaller features to simplify life
for the developer, like:
* the choice of a fully functional graphical user interface or a purely
  command line interface
* wrappers for chrooting into a buildroot or target file-system
  (i.e. bind mounting important system directories and copying over network
   configuration files)
* wrappers for opening Xephyr windows for testing target file-systems
* utilities for creating live USB images of target file-systems for easy
  testing of multiple target file-systems

Installation
------------

It needs below packages that install Image-Creator.
autoconf, automake, intltool

$ ./autogen.sh
$ sudo make install

Running
-------

You must be root in order to run image-creator.  You can either start
image-creator via the desktop menu, in which case image-creator will
automatically run as root (after asking for the root password), or you can
run image-creator from the command-line using sudo.

Also... image-creator can run as a GUI or via the command line. To run the
GUI just start image-creator with no command line arguments:

$ sudo image-creator

To see the available list of command-line arguments:

$ sudo image-creator --help

HINT: image-creator installs a bash completion configuration file, so
      if you are using bash then you can hit tab after typing a few letters
      of a given command line argument and bash will auto-complete or provide
      a list of possible completions. 

Creating a new project from the command line
--------------------------------------------

$ sudo image-creator -c create-project \
                      --platform-name mccaslin-lpia \
                      --project-name "MyProject" \
                      --project-path "/usr/src/myproject" \
                      --project-description "My Samsung Q1 Ultra project" 

The above command will extract the buildroot rootstrap in the
/usr/src/myproject directory, and then use that new file-system to install
additionally needed build packages into.

Once the project is created you can use image-creator to chroot into
the new buildroot via:

$ sudo image-creator -c chroot-project --project-name "MyProject"

Creating a new target from the command line
-------------------------------------------

$ sudo image-creator -c create-target \
                      --project-name "MyProject" \
                      --target-name "target1"

Multiple target file-systems can be created from a single project.  The above
command will generate a new target file-system inside the buildroot at
BUILDROOT/targets/target1/fs/.  You can chroot inside the target file-system
via:

$ sudo image-creator -c chroot-target \
                      --project-name "MyProject" \
                      --target-name "target1"

Installing Target Feature Sets from the command-line
----------------------------------------------------

In image-creator, the platform defines bundles of packages as a fset, where
fsets can have dependencies on other fsets, and installing an fset will
automatically install dependent fsets.

After installing image-creator, you can see an example of an fset
configuration file by looking at: 
/usr/share/sdk/platforms/mccaslin-lpia/fsets/base.fset

<snip>

[Core]
DESC=Fundamental fset that provides a root filesystem
PKGS=linux-image-386
DEBUG_PKGS=gdb man-db manpages
DEPS=


[Hildon-Application-Framework]
DESC=Hildon Application Framework for enabling Mobile Applications
PKGS=ubuntu-mobile sdk-default-icons
DEBUG_PKGS=
DEPS=core

</snip>

From the above snippet you can see two fsets, the "core" fset the provides
additional packages to make it possible to boot a target filesystem
and get to a command line prompt, and a "hildon-application-framework"
fset that will install additional package (on top of core) to enable 
running a Hildon desktop.

To install all needed fsets to boot a Samsung Q1 Ultra and show the current
Hildon Desktop, run:

$ sudo image-creator -c install-fset \
                      --project-name MyProject \
                      --target-name target1 \
                      --fset-name "full-mobile-stack"

Creating a Live USB image of the new target filesystem from the command-line
----------------------------------------------------------------------------

$ sudo image-creator -c create-live-usb \
                      --project-name MyProject \
                      --target-name target1 \
                      --image-name live-usb.img

Image files for a given target are created in the
BUILDROOT/targets/TARGETNAME/image directory.

These image files need to be directly written to a usb key with a tool like dd.
For example:
$ sudo dd if=/usr/src/myproject/targets/target1/image/live-usb.img of=/dev/sdb

WARNING: The above command is only an example!  You must determine what the
         correct device node is for you system.  If you run this command
         with your HD device file then you will trash your installation.

Testing Applications from a Target Filesystem
---------------------------------------------

There a few options for running a virtual target X session inside your 
existing X session running on your workstation.  One popular tool for doing
this is something called Xephyr.  Most modern distributions provide a 
Xephyr package to make using the tool extremely easy.

On Ubuntu you can install Xephyr by running:
$ apt-get install xserver-xephyr

To start a virtual Xsession run:
$ Xephyr :2 -host-cursor -screen 800x480x16 -dpi 96 -ac

This will open a new window that is of size 800x480 and has access controls
turned off.  Any application on your workstation can display inside this
window (as if the window were a new display) by setting the environment 
variable DISPLAY to ":2":
$ export DISPLAY=:2

To run applications from the target filesystem you must first chroot
into the target, then set the DISPLAY and run the application.

$ sudo image-creator -c chroot-target \
                      --project-name MyProject \
                      --target-name target1
# export DISPLAY=:2
# run-my-application

Getting the Source
------------------

The image-creator source is contained in a git source repository.  You can
either view the source on-line via:

http://www.moblin.org/repos/tools/moblin-image-creator.git

...or you can clone the git tree via:

$ git clone rsync://moblin.org/repos/tools/moblin-image-creator.git

NOTE: To install git from Ubuntu, run "sudo apt-get install git-core"

FAQ's
-----

Q:
Why bother with buildroot environment?  Why can't I just install Ubuntu
Gutsy and build my mobile apps directly on my workstation?

A:
Using a buildroot allows the user to isolate the build machine dependencies
from that of the host workstation (or build server.)  Today all MID work
is focused on Gutsy, so using Gutsy on your workstation and then installing
all the needed build dependencies will work, but one of the goals of 
image-creator is to provide a build environment that will continue to work
for a given product long after the product's base distribution has fallen
out of fashion.

Q:
In order to use image-creator to I have to install Ubuntu on my workstation?

A:
When run on an Ubuntu (or any debian derivative distro), it is possible to 
generate RPM packages that work on various RPM based distributions, so while
building image-creator is not supported on a non-debian system, there are
a few pre-built RPM's available on the project download page.

The list of available RPM packages will change over time (depending on demand).

Q:
Why is the image-creator dependent on debian packaging?  Why not use RPM's?

A:
Initial prototyping was actually based on Fedora RPM's using yum to
auto-resolve dependencies in the same way we use apt today.  From day one
the use of yum has proven itself to be less then ideal for the way we wanted
to use it, while at the same time the number of base Fedora package that
we needed to touch were quickly taking us to the point of maintaining a full
distribution.

By moving image-creator to a debian package / apt based implementation and
joining the Ubuntu-Mobile team, we were able to gain advantage from both 
the richer set of debian technologies while at the same time push all of 
our distribution requirements into the upcoming Ubuntu Gutsy repository.

Q:
How does cross compiling work?

A:
Since the initial targets for image-creator are all x86 based, then we
are able to simplify the build by just using the native compiler either
installed in the buildroot or installed on the host workstation (if the
workstation is running the same base as the target.)

Regardless of this, one of the advantages of making image-creator debian
based is that there is a rich set of cross-compiling packages for just
about any architecture.  There shouldn't be any problem in creating a new
platform definition that pulls from an apt database of packages built for
the target architecture, and that build additional packages using existing
cross-compiling technologies.

--------------------------------------------------------------------------

Speeding Up Image-Creator by using a local mirror server

Here is some info on how to speed up image creator. This information has been
updated for LPIA (Low Power Intel Architecture) based builds.

** In order to use this, you must have a local mirror of LPIA Ubuntu Gutsy.
debmirror is a useful command for mirroring a Debian type archive **

If you don't have a mirror server or don't want to set one up, then the next
best thing would probably be to setup a caching proxy server.  This is left as
an exercise for the reader.

Setup root strap mirror servers:

    Create a directory ~/.image-creator/

    Create a file called ~/.image-creator/image-creator.cfg:
    --------------------------------
    [platform]
    buildroot_mirror = http://<path_to_a_local_mirror_of_ubuntu_for_lpia>/
    target_mirror = http://<path_to_a_local_mirror_of_ubuntu_for_lpia>/
    --------------------------------

    You can look at the file: /usr/share/pdk/default_config/defaults.cfg for more
    info on what can go in the: ~/.image-creator/image-creator.cfg file.

Setup sources.list* rewrite rules:

    Create a file called ~/.image-creator/sources_cfg (and sources_cfg is NOT a
    typo, it is an underscore):
    --------------------------------
    sources_regex = [
        # For the Ubuntu LPIA binaries
        # NOTE: The trailing spaces in the strings is important!!
        (r'http://ports.ubuntu.com/ubuntu-ports ', 'http://<path_to_a_local_mirror_of_ubuntu_gutsy_for_lpia>/ '),
        # For the Ubuntu sources, since they are not at ports.ubuntu.com
        (r'http://archive.ubuntu.com/ubuntu ', 'http://<path_to_a_local_mirror_of_ubuntu_gutsy>/ '),
        # For the Moblin.org files
        (r'http://www.moblin.org/apt ', 'http://<path_to_a_local_mirror_of_moblin.org>/ '),
    ]
    --------------------------------

    The purpose of this file is to rewrite the sources.list and
    sources.list.d/* files while they are being copied into the rootstrap. It
    will replace the search expression with the replacement expression.

Delete current rootstraps:

    You have to delete your current rootstraps for this to take affect.

    sudo image-creator --command clear-rootstraps

Caveats:

    This will only affect new projects and new targets. If you do NOT delete
    your rootstraps after doing the above then it will NOT take affect.