README.rst

   1 ======================
   2  User Guide of **mic**
   3 ======================
   4
   5 Overview
   6 ========
   7 The tool `mic` is used to create and manipulate images for Linux distributions.
   8 It's composed of three subcommand: create, convert, chroot. Subcommand `create`
   9 is used to create images with different types, including fs image, loop image,
  10 live CD image, live USB image, raw image, etc. For each image type, there is a
  11 corresponding subcommand. (Details in the following sections)
  12
  13 It supports native running in many mainstream Linux distributions, including:
  14
  15  * Fedora (13 and above)
  16  * openSUSE (11.3 and above)
  17  * Ubuntu (10.04 and above)
  18  * Debian (5.0 and above)
  19  * MeeGo
  20
  21 Installation
  22 ============
  23
  24 Repositories
  25 ------------
  26 So far we support `mic` binary rpms/debs for many popular Linux distributions,
  27 please see the following list. And you can get the corresponding repository on
  28
  29  `<http://download.meego.com/live/devel:/tools:/building>`_
  30
  31 If there is no the distribution you want in the list, please install it from
  32 source code.
  33
  34  * Debian 5.0
  35  * Fedora 13
  36  * Fedora 14
  37  * Fedora 15
  38  * openSUSE 11.3
  39  * openSUSE 11.4
  40  * Ubuntu 10.04
  41  * Ubuntu 10.10
  42
  43 *Tips*: Debian 6.0 can use the repository of Debian 5.0.
  44
  45 Binary Installation
  46 -------------------
  47
  48 Fedora Installation
  49 ~~~~~~~~~~~~~~~~~~~
  50 1. Add devel:tools:building repo:
  51 ::
  52
  53   $ sudo cat <<REPO > /etc/yum.repos.d/devel-tools-building.repo
  54   > [devel-tools-building]
  55   > name=Tools for Fedora
  56   > baseurl=http://download.meego.com/live/devel:/tools:/building/Fedora_<VERSION>
  57   > enabled=1
  58   > gpgcheck=0
  59   > REPO
  60
  61 Also you can take the repo file on devel:tools:building as example. For example,
  62 Fedora 13 can use:
  63 `<http://download.meego.com/live/devel:/tools:/building/Fedora_13/devel:tools:building.repo>`_.
  64
  65 2. Update repolist:
  66 ::
  67
  68   $ sudo yum makecache
  69
  70 3. Install mic:
  71 ::
  72
  73   $ sudo yum install mic
  74
  75 openSUSE Installation
  76 ~~~~~~~~~~~~~~~~~~~~~
  77 1. Add devel:tools:building repo:
  78 ::
  79
  80   $ sudo zypper addrepo http:/download.meego.com/live/devel:/tools:/building/openSUSE_<VERSION>/ devel-tools-building
  81
  82 2. Update repolist:
  83 ::
  84
  85   $ sudo zypper refresh
  86
  87 3. Update libzypp:
  88 ::
  89
  90   $ sudo zypper update libzypp
  91
  92 4. Install mic:
  93 ::
  94
  95   $ sudo zypper install mic
  96
  97 Ubuntu/Debian Installation
  98 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  99 1. Append repo source:
 100 ::
 101
 102   $ sudo cat <<REPO >> /etc/apt-sources.list
 103   > deb http://download.meego.com/live/devel:/tools:/building/<Ubuntu/Debian>_<VERSION>/ /
 104   > REPO
 105
 106 *Tips*: for Ubuntu 10.10, you should use xUbuntu_10.10 to replace <Ubuntu/Debian>_<VERSIN>.
 107
 108 2. Update repolist:
 109 ::
 110
 111   $ sudo apt-get update
 112
 113 3. Install mic:
 114 ::
 115
 116   $ sudo apt-get install mic
 117
 118 Source Installation
 119 -------------------
 120 First, get the source of mic (`<TBD>`_). Then unpack the tar ball, and use make
 121 to process the installation.
 122
 123 1. Unpack:
 124 ::
 125
 126   $ tar xzvf mic.tar.gz
 127
 128 2. Build:
 129 ::
 130
 131   $ cd micng
 132   $ make clean
 133   $ make
 134
 135 3. Install:
 136 ::
 137
 138   $ sudo make install
 139
 140 Configuration file
 141 ==================
 142 A global configure file for mic is provided as `/etc/mic/mic.conf`, where you
 143 can specify the program options statically.
 144 Below is a sample file which is presented in the source: ::
 145
 146   [common]
 147   ; general settings
 148
 149   [create]
 150   ; settings for create subcommand
 151   tmpdir= /var/tmp/mic
 152   cachedir= /var/tmp/mic/cache
 153   outdir= .
 154   pkgmgr = zypp
 155
 156   ; proxy = http://proxy.yourcompany.com:8080/
 157   ; no_proxy = localhost,127.0.0.0/8,.yourcompany.com
 158
 159   [convert]
 160   ; settings for convert subcommand
 161
 162   [chroot]
 163   ; settings for chroot subcommand
 164
 165 For the further development, there are four sections on mic.conf, and [common]
 166 is for general setting, [create], [convert], and [chroot] are prepared for the
 167 options of mic subcommands: create, convert, and chroot.
 168
 169 While you only need set [create] section properly for practice, since other
 170 section would be not effective currently.
 171
 172 +---------+-------------------------------------------------------------------+
 173 | Option  | Usage                                                             |
 174 +=========+===================================================================+
 175 | tmpdir  | temporary directory used to put _instroot and others              |
 176 +---------+-------------------------------------------------------------------+
 177 | cachedir| directory where cached repos will reside also downloaded packages |
 178 +---------+-------------------------------------------------------------------+
 179 | outdir  | where your images will reside once they are created               |
 180 +---------+-------------------------------------------------------------------+
 181 | pkgmgr  | default backend package manager, including yum/zypp               |
 182 +---------+-------------------------------------------------------------------+
 183 | arch    | default repo architecture, like i586, armv7l                      |
 184 +---------+-------------------------------------------------------------------+
 185
 186 Usages
 187 ======
 188 It's recommended to use `--help` or `help <subcmd>` to get the help message, for
 189 the tool is more or less self-documented.
 190
 191 Running 'mic create'
 192 --------------------
 193 Subcommand *create* is used for creating images. To create an image, you should
 194 give the sub-sub commands which presents the image type you want, and also you
 195 should provide an argument which presents the kickstart file for using, such
 196 as: ::
 197
 198   $ sudo mic create fs test.ks
 199
 200 The supported image types can be listed using `mic create --help` ::
 201
 202   fs             create fs image
 203   livecd         create livecd image
 204   liveusb        create liveusb image
 205   loop           create loop image
 206   raw            create raw image
 207
 208 For each image type, you can get their own options by `--help` option, like
 209 `mic cr fs --help`. Meanwhile, there are some common options that can be used
 210 by all image types, see following table:
 211
 212 +------------------+----------------------------------------------------------+
 213 | Option           | Usage                                                    |
 214 +==================+==========================================================+
 215 | -o/--outdir      | specify directory where the images reside                |
 216 +------------------+----------------------------------------------------------+
 217 | -a/--arch        | specify repo architecture, like i586, armv7l, etc        |
 218 +------------------+----------------------------------------------------------+
 219 | -c/--config      | specify the custom configure file for mic                |
 220 +------------------+----------------------------------------------------------+
 221 | --release        | generate release package: image, ks, pkg-list, MANIFEST  |
 222 +------------------+----------------------------------------------------------+
 223 | --logfile        | specify log file to record the output                    |
 224 +------------------+----------------------------------------------------------+
 225 | --local-pkgs-path| directory where local packages can be used when creating |
 226 +------------------+----------------------------------------------------------+
 227 | --pkgmgr         | specify backend package manager                          |
 228 +------------------+----------------------------------------------------------+
 229 | --record-pkgs    | record specified infomation of installed packages,       |
 230 |                  | include name, licence, content.                          |
 231 +------------------+----------------------------------------------------------+
 232
 233 *Tips*: the common options can be normally put before sub-sub command, but also
 234 can be after them, such as: ::
 235
 236   $ sudo mic cr --outdir output fs test.ks
 237
 238 or ::
 239
 240   $ sudo mic cr fs test.ks --outdir output
 241
 242 *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.
 243
 244 Running 'mic chroot'
 245 --------------------
 246 Subcommand *chroot* is used to chroot an image file. Given an image file, you
 247 can use `mic chroot` to chroot inside the image, and then you can do some
 248 modification to the image. After you logout, the image file will keep your
 249 changes. It's a convenient way to hack your image file.
 250
 251 Sample command: ::
 252
 253   $ sudo mic chroot test.img
 254
 255 Running 'mic convert'
 256 ---------------------
 257 Subcommand *convert* is used for converting an image to another one with
 258 different image type. Using `convert`, you can get your needed image type
 259 comfortably. So far converting livecd to liveusb and liveusb to livecd is
 260 supported.
 261
 262 Sample command: ::
 263
 264   $ sudo mic convert test.iso liveusb
 265
 266 Debug/Verbose Output
 267 --------------------
 268 When you encounter some errors, and you want to know more about it, please use
 269 debug/verbose output to get more details in the process by adding `-d/-v`. And
 270 it's recommended to add `-d/--debug` or `-v/--verbose` like: ::
 271
 272   $ sudo mic -d cr fs test.ks