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/liveusb
  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   livecd             create live CD image, used for CD booting
  73   liveusb            create live USB image, used for USB booting
  74   loop               create loop image, including multi-partitions
  75   raw                create raw image, containing multi-partitions
  76
  77 - <ksfile>:
  78
  79 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.
  80
  81 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/daily/trunk/ivi/latest/images/ivi-min...
  82
  83 - Options include:
  84
  85 ::
  86
  87    -h, --help          Show this help message and exit
  88    --logfile=LOGFILE   Path of logfile
  89    -c CONFIG, --config=CONFIG
  90                        Specify config file for MIC
  91    -k CACHEDIR, --cachedir=CACHEDIR
  92                        Cache directory to store downloaded files
  93    -o OUTDIR, --outdir=OUTDIR
  94                        Output directory
  95    -A ARCH, --arch=ARCH
  96                        Specify repo architecture
  97    --release=RID       Generate a release of RID with all necessary files.
  98                        When @BUILD_ID@ is contained in kickstart file, it
  99                        will be replaced by RID.
 100    --record-pkgs=RECORD_PKGS
 101                        Record the info of installed packages. Multiple values
 102                        can be specified which joined by ",", valid values:
 103                        "name", "content", "license".
 104    --pkgmgr=PKGMGR     Specify backend package manager
 105    --local-pkgs-path=LOCAL_PKGS_PATH
 106                        Path for local pkgs(rpms) to be installed
 107    --pack-to=PACK_TO   Pack the images together into the specified achive,
 108                        extension supported: .zip, .tar, .tar.gz, .tar.bz2,
 109                        etc. by default, .tar will be used
 110    --copy-kernel       Copy kernel files from image /boot directory to the
 111                        image output directory.
 112
 113 - Other options:
 114
 115 ::
 116
 117    --runtime=RUNTIME_MODE
 118                        Sets runtime mode, the default is bootstrap mode, valid
 119                        values: "bootstrap". "bootstrap"  means mic uses one
 120                        tizen chroot environment to create image.
 121     --compress-image=COMPRESS_IMAGE (for loop & raw)
 122                        Sets the disk image compression. Note: The available
 123                        values might depend on the used filesystem type.
 124    --compress-disk-image=COMPRESS_IMAGE
 125                        Same with --compress-image
 126    --shrink (for loop)
 127                        Whether to shrink loop images to minimal size
 128    --generate-bmap (for raw)
 129                        Generate the block map file
 130
 131 - Examples:
 132
 133 ::
 134
 135    mic cr loop tizen.ks
 136
 137 Chroot
 138 ------
 139 This command is used to chroot inside the image. It's a great enhancement of the chroot command in the Linux system.
 140
 141 - Usage:
 142
 143 ::
 144
 145    mic chroot(ch) <imgfile>
 146
 147 - Options:
 148
 149 ::
 150
 151    -h, --help          Show this help message and exit
 152    -s SAVETO, --saveto=SAVETO
 153                        Save the unpacked image to a specified dir
 154
 155 - Examples:
 156
 157 ::
 158
 159    mic ch loop.img
 160    mic ch tizen.iso
 161    mic ch -s tizenfs tizen.usbimg
 162
 163 Convert
 164 -------
 165 This command is used for converting an image to another format.
 166
 167
 168 - Usage:
 169
 170 ::
 171
 172    mic convert(cv) <imagefile> <destformat>
 173
 174 - Options:
 175
 176 ::
 177
 178    -h, --help   Show this help message and exit
 179    -S, --shell  Launch shell before packaging the converted image
 180
 181 - Examples:
 182
 183 ::
 184
 185    mic cv tizen.iso liveusb
 186    mic cv tizen.usbimg livecd
 187    mic cv --shell tizen.iso liveusb
 188
 189 Getting Start
 190 -------------
 191
 192 How to create an image
 193 ~~~~~~~~~~~~~~~~~~~~~~~
 194
 195 **Prepare kickstart file**
 196
 197 To create an image, you need a proper ks file.
 198 Here's a simple example:
 199 ::
 200
 201   # filename: tizen-min.ks
 202   lang en_US.UTF-8
 203   keyboard us
 204   timezone --utc America/Los_Angeles
 205
 206   part / --size 1824 --ondisk sda --fstype=ext3
 207
 208   rootpw tizen
 209   bootloader  --timeout=0  --append="rootdelay=5"
 210
 211   desktop --autologinuser=tizen
 212   user --name tizen  --groups audio,video --password 'tizen'
 213
 214   repo --name=Tizen-base --baseurl=http://download.tizen.org/snapshots/trunk/latest/repos/base/ia32/packages/
 215   repo --name=Tizen-main --baseurl=http://download.tizen.org/snapshots/trunk/latest/repos/main/ia32/packages/
 216
 217   %packages --ignoremissing
 218    @tizen-bootstrap
 219   %end
 220
 221   %post
 222   rm -rf /var/lib/rpm/__db*
 223   rpm --rebuilddb
 224   %end
 225
 226   %post --nochroot
 227   %end
 228
 229 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:
 230 ::
 231
 232   repo --name=REPO-NAME --baseurl=https://username:passwd@yourrepo.com/ia32/packages/ --save  --ssl_verify=no
 233
 234 **Create an loop image**
 235
 236 To create an image, run MIC in the terminal:
 237 ::
 238
 239  $ sudo mic create loop tizen-min.ks
 240
 241 How to add/remove packages
 242 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 243
 244 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/_.
 245
 246 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:
 247 ::
 248
 249   %packages
 250   ...
 251   @Tizen Core            # add a group named Tizen Core, and all the packages in this group would be added
 252   e17-*                  # add all the packages with name starting with "e17-"
 253   kernel                 # add kernel package
 254   nss-server.armv7hl     # add nss-server with arch armv7hl
 255   -passwd                # remove the package passwd
 256   ...
 257   %end
 258
 259 Use local rpm package
 260 ~~~~~~~~~~~~~~~~~~~~~
 261
 262 "How can I install my own rpm into the image, so I can test my package with the image?"
 263 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:
 264
 265 ::
 266
 267     $ sudo mic create loop test.ks --local-pkgs-path=localpath
 268
 269 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.
 270
 271 How to set proxy
 272 ~~~~~~~~~~~~~~~~
 273
 274 **Proxy variable in bash**
 275
 276 It's common to use the proxy variable in bash. In general, you can set the following environment variables to enable proxy support:
 277
 278 ::
 279
 280   export http_proxy=http://proxy.com:port
 281   export https_proxy=http://proxy.com:port
 282   export ftp_proxy=http://proxy.com:port
 283   export no_proxy=localhost,127.0.0.0/8,.company.com
 284
 285 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.
 286
 287 Because MIC needs sudo privilege, set /etc/sudoers, to keep the proxy environment, and add those proxy variables to "env_keep":
 288
 289 ::
 290
 291    Defaults        env_keep += "http_proxy https_proxy ftp_proxy no_proxy"
 292
 293 Note: Use "visudo" to modify /etc/sudoers
 294
 295 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.
 296
 297 **Proxy setting in mic.conf**
 298
 299 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:
 300
 301 ::
 302
 303   [create]
 304    ; settings for create subcommand
 305    tmpdir= /var/tmp/mic
 306    cachedir= /var/tmp/mic/cache
 307    outdir= .
 308    pkgmgr = zypp
 309    proxy = http://proxy.yourcompany.com:8080/
 310    no_proxy = localhost,127.0.0.0/8,.yourcompany.com
 311
 312 **Proxy setting in ks file**
 313
 314 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.
 315 Here's how to handle that case:
 316
 317 ::
 318
 319   repo --name=oss --baseurl=http://www.example.com/repos/oss/packages --proxy=http://host:port
 320
 321 What's BootStrap?
 322 ~~~~~~~~~~~~~~~~~
 323 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.
 324
 325 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.
 326