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