path: root/README.rst

======================
 User Guide of **mic**
======================

Overview
========
The tool `mic` is used to create and manipulate images for Linux distributions.
It's composed of three subcommand: create, convert, chroot. Subcommand `create`
is used to create images with different types, including fs image, loop image,
live CD image, live USB image, raw image, etc. For each image type, there is a
corresponding subcommand. (Details in the following sections)

It supports native running in many mainstream Linux distributions, including:

 * Fedora (13 and above)
 * openSUSE (11.3 and above)
 * Ubuntu (10.04 and above)
 * Debian (5.0 and above)
 * MeeGo

Installation
============

Repositories
------------
So far we support `mic` binary rpms/debs for many popular Linux distributions,
please see the following list. And you can get the corresponding repository on

 `<http://download.meego.com/live/devel:/tools:/building>`_

If there is no the distribution you want in the list, please install it from
source code.

 * Debian 5.0
 * Fedora 13
 * Fedora 14
 * Fedora 15
 * openSUSE 11.3
 * openSUSE 11.4
 * Ubuntu 10.04
 * Ubuntu 10.10

*Tips*: Debian 6.0 can use the repository of Debian 5.0.

Binary Installation
-------------------

Fedora Installation
~~~~~~~~~~~~~~~~~~~
1. Add devel:tools:building repo:
::

  $ sudo cat <<REPO > /etc/yum.repos.d/devel-tools-building.repo
  > [devel-tools-building]
  > name=Tools for Fedora
  > baseurl=http://download.meego.com/live/devel:/tools:/building/Fedora_<VERSION>
  > enabled=1
  > gpgcheck=0
  > REPO

Also you can take the repo file on devel:tools:building as example. For example,
Fedora 13 can use:
`<http://download.meego.com/live/devel:/tools:/building/Fedora_13/devel:tools:building.repo>`_.

2. Update repolist:
::

  $ sudo yum makecache

3. Install mic:
::

  $ sudo yum install mic

openSUSE Installation
~~~~~~~~~~~~~~~~~~~~~
1. Add devel:tools:building repo:
::

  $ sudo zypper addrepo http:/download.meego.com/live/devel:/tools:/building/openSUSE_<VERSION>/ devel-tools-building

2. Update repolist:
::

  $ sudo zypper refresh

3. Update libzypp:
::

  $ sudo zypper update libzypp

4. Install mic:
::

  $ sudo zypper install mic

Ubuntu/Debian Installation
~~~~~~~~~~~~~~~~~~~~~~~~~~
1. Append repo source:
::

  $ sudo cat <<REPO >> /etc/apt-sources.list
  > deb http://download.meego.com/live/devel:/tools:/building/<Ubuntu/Debian>_<VERSION>/ /
  > REPO

*Tips*: for Ubuntu 10.10, you should use xUbuntu_10.10 to replace <Ubuntu/Debian>_<VERSIN>.

2. Update repolist:
::

  $ sudo apt-get update

3. Install mic:
::

  $ sudo apt-get install mic

Source Installation
-------------------
First, get the source of mic (`<TBD>`_). Then unpack the tar ball, and use make
to process the installation.

1. Unpack:
::

  $ tar xzvf mic.tar.gz

2. Build:
::

  $ cd micng
  $ make clean
  $ make

3. Install:
::

  $ sudo make install

Configuration file
==================
A global configure file for mic is provided as `/etc/mic/mic.conf`, where you
can specify the program options statically.
Below is a sample file which is presented in the source: ::

  [common]
  ; general settings
  
  [create]
  ; settings for create subcommand
  tmpdir= /var/tmp/mic
  cachedir= /var/tmp/mic/cache
  outdir= .
  pkgmgr = zypp
  
  ; proxy = http://proxy.yourcompany.com:8080/
  ; no_proxy = localhost,127.0.0.0/8,.yourcompany.com
  
  [convert]
  ; settings for convert subcommand
  
  [chroot]
  ; settings for chroot subcommand

For the further development, there are four sections on mic.conf, and [common]
is for general setting, [create], [convert], and [chroot] are prepared for the
options of mic subcommands: create, convert, and chroot.

While you only need set [create] section properly for practice, since other
section would be not effective currently.

+---------+-------------------------------------------------------------------+
| Option  | Usage                                                             |
+=========+===================================================================+
| tmpdir  | temporary directory used to put _instroot and others              |
+---------+-------------------------------------------------------------------+
| cachedir| directory where cached repos will reside also downloaded packages |
+---------+-------------------------------------------------------------------+
| outdir  | where your images will reside once they are created               |
+---------+-------------------------------------------------------------------+
| pkgmgr  | default backend package manager, including yum/zypp               |
+---------+-------------------------------------------------------------------+
| arch    | default repo architecture, like i586, armv7l                      |
+---------+-------------------------------------------------------------------+

Usages
======
It's recommended to use `--help` or `help <subcmd>` to get the help message, for
the tool is more or less self-documented.

Running 'mic create'
--------------------
Subcommand *create* is used for creating images. To create an image, you should
give the sub-sub commands which presents the image type you want, and also you
should provide an argument which presents the kickstart file for using, such
as: ::

  $ sudo mic create fs test.ks

The supported image types can be listed using `mic create --help` ::

  fs             create fs image
  livecd         create livecd image
  liveusb        create liveusb image
  loop           create loop image
  raw            create raw image

For each image type, you can get their own options by `--help` option, like
`mic cr fs --help`. Meanwhile, there are some common options that can be used
by all image types, see following table:

+------------------+----------------------------------------------------------+
| Option           | Usage                                                    |
+==================+==========================================================+
| -o/--outdir      | specify directory where the images reside                |
+------------------+----------------------------------------------------------+
| -a/--arch        | specify repo architecture, like i586, armv7l, etc        |
+------------------+----------------------------------------------------------+
| -c/--config      | specify the custom configure file for mic                |
+------------------+----------------------------------------------------------+
| --release        | generate release package: image, ks, pkg-list, MANIFEST  |
+------------------+----------------------------------------------------------+
| --logfile        | specify log file to record the output                    |
+------------------+----------------------------------------------------------+
| --local-pkgs-path| directory where local packages can be used when creating |
+------------------+----------------------------------------------------------+
| --pkgmgr         | specify backend package manager                          |
+------------------+----------------------------------------------------------+
| --record-pkgs    | record specified infomation of installed packages,       |
|                  | include name, licence, content.                          |
+------------------+----------------------------------------------------------+

*Tips*: the common options can be normally put before sub-sub command, but also
can be after them, such as: ::

  $ sudo mic cr --outdir output fs test.ks

or ::

  $ sudo mic cr fs test.ks --outdir output

*Tips*: if you failed to create armv7* image, the reason may be qemu/qemu-arm on your host is lower than required, please update qemu/qemu-arm higher than 0.13.0.

Running 'mic chroot'
--------------------
Subcommand *chroot* is used to chroot an image file. Given an image file, you
can use `mic chroot` to chroot inside the image, and then you can do some
modification to the image. After you logout, the image file will keep your
changes. It's a convenient way to hack your image file.

Sample command: ::

  $ sudo mic chroot test.img

Running 'mic convert'
---------------------
Subcommand *convert* is used for converting an image to another one with
different image type. Using `convert`, you can get your needed image type
comfortably. So far converting livecd to liveusb and liveusb to livecd is
supported.

Sample command: ::

  $ sudo mic convert test.iso liveusb

Debug/Verbose Output
--------------------
When you encounter some errors, and you want to know more about it, please use
debug/verbose output to get more details in the process by adding `-d/-v`. And
it's recommended to add `-d/--debug` or `-v/--verbose` like: ::

  $ sudo mic -d cr fs test.ks