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