doc/usage.rst

   1 MIC Usage
   2 =========
   3
   4 .. contents:: Table of Contents
   5
   6 Overview
   7 --------
   8 MIC offers three major functions:
   9
  10 - creating an image with different format
  11 - converting an image to another format
  12 - chrooting into an image
  13
  14 Getting help
  15 ------------
  16 You can also use `$ mic --help` or `$ mic <subcmd> --help`  to get the help message.
  17
  18 How to get help:
  19
  20 - using 'man'
  21
  22   * man mic
  23
  24 - using '--help' option
  25
  26   * mic --help
  27   * mic create --help
  28   * mic help create
  29   * mic create loop --help
  30   * mic create help loop
  31
  32 Image formulation support
  33 -------------------------
  34 - Loop
  35
  36   * Each loop corresponds to one partition
  37   * A file system will be created inside the image
  38   * For a configuration with multiple partitions, which is specified in the kickstartfile, mic will generate multiple loop images
  39   * And multiple loop images can be packed into a single archive file
  40
  41 - Raw
  42
  43   * “raw” format means something like hard disk dumping
  44   * Including partition table and all the partitions
  45   * The image is bootable directly
  46
  47 - Livecd
  48
  49   * Mainly used for an ia32 build, it can be burned to CD or usbstick, which can be booted into a live system or installation UI
  50
  51 - fs
  52
  53   * “fs” means file-system
  54   * mic can install all the Tizen files to the specified directory, which can be used directly as chroot env
  55
  56
  57 Create
  58 ------
  59 - Command line for image creation:
  60
  61 ::
  62
  63   mic create(cr) SUBCOMMAND <ksfile> [OPTION]
  64
  65
  66 - Sub-commands, to specify image format, include:
  67
  68 ::
  69
  70   help(?)            give detailed help on a specific sub-command
  71   fs                 create fs image, which is also a chroot directory
  72   loop               create loop image, including multi-partitions
  73
  74 - <ksfile>:
  75
  76 The kickstart file is a simple text file, containing a list of items about image partition, setup, Bootloader, packages to be installed, etc, each identified by a keyword.
  77
  78 In Tizen, the released image will have a ks file along with image. For example, you can download the ks file from: http://download.tizen.org/releases/weekly/tizen/mobile/latest/images/...
  79
  80 - Options include:
  81
  82 ::
  83
  84    -h, --help          Show this help message and exit
  85    --logfile=LOGFILE   Path of logfile
  86    -c CONFIG, --config=CONFIG
  87                        Specify config file for MIC
  88    -k CACHEDIR, --cachedir=CACHEDIR
  89                        Cache directory to store downloaded files
  90    -o OUTDIR, --outdir=OUTDIR
  91                        Output directory
  92    -A ARCH, --arch=ARCH
  93                        Specify repo architecture
  94    --release=RID       Generate a release of RID with all necessary files.
  95                        When @BUILD_ID@ is contained in kickstart file, it
  96                        will be replaced by RID.
  97    --record-pkgs=RECORD_PKGS
  98                        Record the info of installed packages. Multiple values
  99                        can be specified which joined by ",", valid values:
 100                        "name", "content", "license".
 101    --pkgmgr=PKGMGR     Specify backend package manager
 102    --local-pkgs-path=LOCAL_PKGS_PATH
 103                        Path for local pkgs(rpms) to be installed
 104    --pack-to=PACK_TO   Pack the images together into the specified achive,
 105                        extension supported: .zip, .tar, .tar.gz, .tar.bz2,
 106                        etc. by default, .tar will be used
 107    --copy-kernel       Copy kernel files from image /boot directory to the
 108                        image output directory.
 109
 110 - Other options:
 111
 112 ::
 113
 114    --runtime=RUNTIME_MODE
 115                        Sets runtime mode, the default is bootstrap mode, valid
 116                        values: "bootstrap". "bootstrap"  means mic uses one
 117                        tizen chroot environment to create image.
 118     --compress-image=COMPRESS_IMAGE (for loop & raw)
 119                        Sets the disk image compression. Note: The available
 120                        values might depend on the used filesystem type.
 121    --compress-disk-image=COMPRESS_IMAGE
 122                        Same with --compress-image
 123    --shrink (for loop)
 124                        Whether to shrink loop images to minimal size
 125    --generate-bmap (for raw)
 126                        Generate the block map file
 127
 128 - Examples:
 129
 130 ::
 131
 132    mic cr loop tizen.ks
 133
 134 Chroot
 135 ------
 136 This command is used to chroot inside the image. It's a great enhancement of the chroot command in the Linux system.
 137
 138 - Usage:
 139
 140 ::
 141
 142    mic chroot(ch) <imgfile>
 143
 144 - Options:
 145
 146 ::
 147
 148    -h, --help          Show this help message and exit
 149    -s SAVETO, --saveto=SAVETO
 150                        Save the unpacked image to a specified dir
 151
 152 - Examples:
 153
 154 ::
 155
 156    mic ch loop.img
 157    mic ch tizen.iso
 158    mic ch -s tizenfs tizen.usbimg
 159
 160 Convert
 161 -------
 162 This command is used for converting an image to another format.
 163
 164
 165 - Usage:
 166
 167 ::
 168
 169    mic convert(cv) <imagefile> <destformat>
 170
 171 - Options:
 172
 173 ::
 174
 175    -h, --help   Show this help message and exit
 176    -S, --shell  Launch shell before packaging the converted image
 177
 178 - Examples:
 179
 180 ::
 181
 182    mic cv tizen.usbimg livecd
 183
 184 Getting Start
 185 -------------
 186
 187 How to create an image
 188 ~~~~~~~~~~~~~~~~~~~~~~~
 189
 190 **Prepare kickstart file**
 191
 192 To create an image, you need a proper ks file.
 193 Here's a simple example:
 194 ::
 195
 196   # filename: tizen-min.ks
 197   lang en_US.UTF-8
 198   keyboard us
 199   timezone --utc America/Los_Angeles
 200
 201   part / --size 1824 --ondisk sda --fstype=ext3
 202
 203   rootpw tizen
 204   bootloader  --timeout=0  --append="rootdelay=5"
 205
 206   desktop --autologinuser=tizen
 207   user --name tizen  --groups audio,video --password 'tizen'
 208
 209   repo --name=Tizen-base --baseurl=http://download.tizen.org/snapshots/trunk/latest/repos/base/ia32/packages/
 210   repo --name=Tizen-main --baseurl=http://download.tizen.org/snapshots/trunk/latest/repos/main/ia32/packages/
 211
 212   %packages --ignoremissing
 213    @tizen-bootstrap
 214   %end
 215
 216   %post
 217   rm -rf /var/lib/rpm/__db*
 218   rpm --rebuilddb
 219   %end
 220
 221   %post --nochroot
 222   %end
 223
 224 The ks file above can be used to create a minimum Tizen image. For other repositories, you can replace with the appropriate repository url. For example:
 225 ::
 226
 227   repo --name=REPO-NAME --baseurl=https://username:passwd@yourrepo.com/ia32/packages/ --save  --ssl_verify=no
 228
 229 **Create an loop image**
 230
 231 To create an image, run MIC in the terminal:
 232 ::
 233
 234  $ sudo mic create loop tizen-min.ks
 235
 236 How to add/remove packages
 237 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 238
 239 You can specific the packages you plan to install in the '%packages' section in ks file. Packages can be specified by group/pattern or by individual package name. The definition of the groups/pattern can be referred to in the repodata/\*comps.xml or repodata/pattern.xml file at the download server. For example: http://download.tizen.org/snapshots/latest/repos/base/ia32/packages/repodata/_.
 240
 241 The %packages section is required to end with '%end'. Also, multiple '%packages' sections are allowed. Additionally, individual packages may be specified using globs. For example:
 242 ::
 243
 244   %packages
 245   ...
 246   @Tizen Core            # add a group named Tizen Core, and all the packages in this group would be added
 247   e17-*                  # add all the packages with name starting with "e17-"
 248   kernel                 # add kernel package
 249   nss-server.armv7hl     # add nss-server with arch armv7hl
 250   -passwd                # remove the package passwd
 251   ...
 252   %end
 253
 254 Use local rpm package
 255 ~~~~~~~~~~~~~~~~~~~~~
 256
 257 "How can I install my own rpm into the image, so I can test my package with the image?"
 258 In such a case, using local package path would be very helpful. For example, if your rpm 'hello.rpm' is under directory 'localpath', run MIC like below:
 259
 260 ::
 261
 262     $ sudo mic create loop test.ks --local-pkgs-path=localpath
 263
 264 From the output, MIC will tell you "Marked 'hellop.rpm' as installed", and it will install hello.rpm in the image. Be sure your rpm is not in the repo of ks file and that your rpm's version is newer or equal to the repo rpm version.
 265
 266 How to set proxy
 267 ~~~~~~~~~~~~~~~~
 268
 269 **Proxy variable in bash**
 270
 271 It's common to use the proxy variable in bash. In general, you can set the following environment variables to enable proxy support:
 272
 273 ::
 274
 275   export http_proxy=http://proxy.com:port
 276   export https_proxy=http://proxy.com:port
 277   export ftp_proxy=http://proxy.com:port
 278   export no_proxy=localhost,127.0.0.0/8,.company.com
 279
 280 You don't need all the variables. Check what you do need. When your repo url in your ks file starts with 'https', MIC will use https_proxy. Be especially aware of when you set no_proxy (it indicates which domain should be accessed directly). Don't leave blank space in the string.
 281
 282 Because MIC needs sudo privilege, set /etc/sudoers, to keep the proxy environment, and add those proxy variables to "env_keep":
 283
 284 ::
 285
 286    Defaults        env_keep += "http_proxy https_proxy ftp_proxy no_proxy"
 287
 288 Note: Use "visudo" to modify /etc/sudoers
 289
 290 However, if you don't want to change your /etc/sudoers, there is an alternative for you to set the proxy in mic.conf. See the next section.
 291
 292 **Proxy setting in mic.conf**
 293
 294 The proxy environment variables may disturb other program, so if you would like to enable proxy support only for MIC, set the proxy in /etc/mic/mic.conf like this:
 295
 296 ::
 297
 298   [create]
 299    ; settings for create subcommand
 300    tmpdir= /var/tmp/mic
 301    cachedir= /var/tmp/mic/cache
 302    outdir= .
 303    pkgmgr = zypp
 304    proxy = http://proxy.yourcompany.com:8080/
 305    no_proxy = localhost,127.0.0.0/8,.yourcompany.com
 306
 307 **Proxy setting in ks file**
 308
 309 It's likely that you will need to enable proxy support only for a special repo url, and other things would remain at their existing proxy setting.
 310 Here's how to handle that case:
 311
 312 ::
 313
 314   repo --name=oss --baseurl=http://www.example.com/repos/oss/packages --proxy=http://host:port
 315
 316 What's BootStrap?
 317 ~~~~~~~~~~~~~~~~~
 318 When some important packages (like rpm) of the distribution (Tizen) is much different with native environment, the image created by native environment may be not bootable. Then a bootstrap environment will be required to create the image.
 319
 320 To create an image of one distribution (Tizen), MIC will create a bootstrap for this distribution (Tizen) at first, and then create the image by chrooting this bootstrap. This way is called "Bootstrap Mode" for MIC. And from 0.15 on, MIC will use this mode by default.
 321