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 - chrooting into an image
  12
  13 Getting help
  14 ------------
  15 You can also use `$ mic --help` or `$ mic <subcmd> --help`  to get the help message.
  16
  17 How to get help:
  18
  19 - using 'man'
  20
  21   * man mic
  22
  23 - using '--help' option
  24
  25   * mic --help
  26   * mic create --help
  27   * mic create loop --help
  28
  29 Image formulation support
  30 -------------------------
  31 - Loop
  32
  33   * Each loop corresponds to one partition
  34   * A file system will be created inside the image
  35   * For a configuration with multiple partitions, which is specified in the kickstartfile, mic will generate multiple loop images
  36   * And multiple loop images can be packed into a single archive file
  37
  38 - fs
  39
  40   * “fs” means file-system
  41   * mic can install all the Tizen files to the specified directory, which can be used directly as chroot env
  42
  43 - qcow
  44
  45
  46 Create
  47 ------
  48 - Command line for image creation:
  49
  50 ::
  51
  52   mic [GLOBAL-OPTS] create(cr) SUBCOMMAND <ksfile> [OPTION]
  53
  54
  55 - Sub-commands, to specify image format, include:
  56
  57 ::
  58
  59   auto               auto detect image type from magic header
  60   fs                 create fs image, which is also a chroot directory
  61   loop               create loop image, including multi-partitions
  62   qcow               create qcow image
  63
  64 - <ksfile>:
  65
  66 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.
  67
  68 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/...
  69
  70 - Options include:
  71
  72 ::
  73
  74    -h, --help          Show this help message and exit
  75    --logfile=LOGFILE   Path of logfile
  76    -c CONFIG, --config=CONFIG
  77                        Specify config file for MIC
  78    -k CACHEDIR, --cachedir=CACHEDIR
  79                        Cache directory to store downloaded files
  80    -o OUTDIR, --outdir=OUTDIR
  81                        Output directory
  82    -A ARCH, --arch=ARCH
  83                        Specify repo architecture
  84    --release=RID       Generate a release of RID with all necessary files.
  85                        When @BUILD_ID@ is contained in kickstart file, it
  86                        will be replaced by RID.
  87    --record-pkgs=RECORD_PKGS
  88                        Record the info of installed packages. Multiple values
  89                        can be specified which joined by ",", valid values:
  90                        "name", "content", "license".
  91    --pkgmgr=PKGMGR     Specify backend package manager
  92    --local-pkgs-path=LOCAL_PKGS_PATH
  93                        Path for local pkgs(rpms) to be installed
  94    --pack-to=PACK_TO   Pack the images together into the specified achive,
  95                        extension supported: .zip, .tar, .tar.gz, .tar.bz2,
  96                        etc. by default, .tar will be used
  97    --runtime=RUNTIME_MODE
  98                        Sets runtime mode, the default is bootstrap mode, valid
  99                        values: "bootstrap". "bootstrap"  means mic uses one
 100                        tizen chroot environment to create image.
 101    --copy-kernel       Copy kernel files from image /boot directory to the
 102                        image output directory.
 103    --install-pkgs      INSTALL_PKGS  Specify what type of packages to be
 104                        installed, valid: source, debuginfo, debugsource
 105    --check-pkgs=CHECK_PKGS
 106                        Check if given packages would be installed,
 107                        packages should be separated by comma
 108    --tmpfs             Setup tmpdir as tmpfs to accelerate, experimental feature,
 109                        use it if you have more than 4G memory
 110    --strict-mode       Abort creation of image, if there are some errors
 111                        during rpm installation
 112
 113 - Other options:
 114
 115 ::
 116
 117    --compress-image=COMPRESS_IMAGE (for loop)
 118                        Sets the disk image compression. Note: The available
 119                        values might depend on the used filesystem type.
 120    --compress-disk-image=COMPRESS_IMAGE
 121                        Same with --compress-image
 122    --shrink (for loop)
 123                        Whether to shrink loop images to minimal size
 124    --include-src (for fs)
 125                        Generate a image with source rpms included
 126 - Examples:
 127
 128 ::
 129
 130    mic cr loop tizen.ks
 131
 132 Chroot
 133 ------
 134 This command is used to chroot inside the image. It's a great enhancement of the chroot command in the Linux system.
 135
 136 - Usage:
 137
 138 ::
 139
 140    mic chroot(ch) <imgfile>
 141
 142 - Options:
 143
 144 ::
 145
 146    -h, --help          Show this help message and exit
 147    -s SAVETO, --saveto=SAVETO
 148                        Save the unpacked image to a specified dir
 149
 150 - Examples:
 151
 152 ::
 153
 154    mic ch loop.img
 155
 156 Getting Start
 157 -------------
 158
 159 How to create an image
 160 ~~~~~~~~~~~~~~~~~~~~~~~
 161
 162 **Prepare kickstart file**
 163
 164 To create an image, you need a proper ks file.
 165 Here's a simple example:
 166 ::
 167
 168   # filename: tizen-min.ks
 169   lang en_US.UTF-8
 170   keyboard us
 171   timezone --utc America/Los_Angeles
 172
 173   part / --size 1824 --ondisk sda --fstype=ext3
 174
 175   rootpw tizen
 176   bootloader  --timeout=0  --append="rootdelay=5"
 177
 178   desktop --autologinuser=tizen
 179   user --name tizen  --groups audio,video --password 'tizen'
 180
 181   repo --name=Tizen-base --baseurl=http://download.tizen.org/snapshots/trunk/latest/repos/base/ia32/packages/
 182   repo --name=Tizen-main --baseurl=http://download.tizen.org/snapshots/trunk/latest/repos/main/ia32/packages/
 183
 184   %packages --ignoremissing
 185    @tizen-bootstrap
 186   %end
 187
 188   %post
 189   rm -rf /var/lib/rpm/__db*
 190   rpm --rebuilddb
 191   %end
 192
 193   %post --nochroot
 194   %end
 195
 196 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:
 197 ::
 198
 199   repo --name=REPO-NAME --baseurl=https://username:passwd@yourrepo.com/ia32/packages/ --save  --ssl_verify=no
 200
 201 **Create an loop image**
 202
 203 To create an image, run MIC in the terminal:
 204 ::
 205
 206  $ sudo mic create loop tizen-min.ks
 207
 208 How to add/remove packages
 209 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 210
 211 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/_.
 212
 213 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:
 214 ::
 215
 216   %packages
 217   ...
 218   @Tizen Core            # add a group named Tizen Core, and all the packages in this group would be added
 219   e17-*                  # add all the packages with name starting with "e17-"
 220   kernel                 # add kernel package
 221   nss-server.armv7hl     # add nss-server with arch armv7hl
 222   -passwd                # remove the package passwd
 223   ...
 224   %end
 225
 226 Use local rpm package
 227 ~~~~~~~~~~~~~~~~~~~~~
 228
 229 "How can I install my own rpm into the image, so I can test my package with the image?"
 230 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:
 231
 232 ::
 233
 234     $ sudo mic create loop test.ks --local-pkgs-path=localpath
 235
 236 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.
 237
 238 How to set proxy
 239 ~~~~~~~~~~~~~~~~
 240
 241 **Proxy variable in bash**
 242
 243 It's common to use the proxy variable in bash. In general, you can set the following environment variables to enable proxy support:
 244
 245 ::
 246
 247   export http_proxy=http://proxy.com:port
 248   export https_proxy=http://proxy.com:port
 249   export ftp_proxy=http://proxy.com:port
 250   export no_proxy=localhost,127.0.0.0/8,.company.com
 251
 252 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.
 253
 254 Because MIC needs sudo privilege, set /etc/sudoers, to keep the proxy environment, and add those proxy variables to "env_keep":
 255
 256 ::
 257
 258    Defaults        env_keep += "http_proxy https_proxy ftp_proxy no_proxy"
 259
 260 Note: Use "visudo" to modify /etc/sudoers
 261
 262 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.
 263
 264 **Proxy setting in mic.conf**
 265
 266 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:
 267
 268 ::
 269
 270   [create]
 271    ; settings for create subcommand
 272    tmpdir= /var/tmp/mic
 273    cachedir= /var/tmp/mic/cache
 274    outdir= .
 275    pkgmgr = zypp
 276    proxy = http://proxy.yourcompany.com:8080/
 277    no_proxy = localhost,127.0.0.0/8,.yourcompany.com
 278
 279 **Proxy setting in ks file**
 280
 281 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.
 282 Here's how to handle that case:
 283
 284 ::
 285
 286   repo --name=oss --baseurl=http://www.example.com/repos/oss/packages --proxy=http://host:port
 287
 288 What's BootStrap?
 289 ~~~~~~~~~~~~~~~~~
 290 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.
 291
 292 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.
 293