doc/man.rst

   1 =====
   2  mic
   3 =====
   4
   5 SYNOPSIS
   6 ========
   7
   8 | mic create SUBCOMMAND <ksfile> [OPTION]
   9 | mic chroot [OPTION] <imgfile>
  10 | mic convert [OPTION] <imgfile> <format>
  11
  12 DESCRIPTION
  13 ===========
  14
  15 The tools `mic` is used to create and manipulate images for Linux distributions.
  16 It is composed of three subcommand: `create`, `convert`, `chroot`.
  17
  18 USAGE
  19 =====
  20
  21 create
  22 ------
  23 This command is used to create various images, including live CD, live USB,
  24 loop, raw.
  25
  26 Usage:
  27
  28  | mic create(cr) SUBCOMMAND <ksfile> [OPTION]
  29
  30 Subcommands:
  31
  32  | help(?)      give detailed help on a specific sub-command
  33  | fs           create fs image, which is also chroot directory
  34  | livecd       create live CD image, used for CD booting
  35  | liveusb      create live USB image, used for USB booting
  36  | loop         create loop image, including multi-partitions
  37  | raw          create raw image, containing multi-partitions
  38
  39 Options:
  40
  41   -h, --help  show the help message
  42   --logfile=LOGFILE  specify the path of logfile, save the output to logfile LOGFILE
  43   -c CONFIG, --config=CONFIG  specify configure file for mic, default is /etc/mic/mic.conf
  44   -k CACHEDIR, --cachedir=CACHEDIR  cache directory used to store the downloaded files and packages
  45   -o OUTDIR, --outdir=OUTDIR  directory used to locate the output image and files
  46   -A ARCH, --arch=ARCH  specify repo architecture, genarally mic would detect the architecture, if existed more than one architecture, mic would give hint to you
  47   --local-pkgs-path=LOCAL_PKGS_PATH  specify the path for local rpm packages, which would be stored your own rpm packages
  48   --pkgmgr=PKGMGR  specify backend package mananger, currently yum and zypp available
  49   --record-pkgs=RECORD_PKGS  record the info of installed packages, multiple values can be specified which joined by ",", valid values: "name", "content", "license"
  50   --pack-to=PACK_TO   pack the images together into the specified achive, extension supported: .zip, .tar, .tar.gz, .tar.bz2, etc. by default, .tar will be used
  51   --release=RID  generate a release of RID with all necessary files, when @BUILD_ID@ is contained in kickstart file, it will be replaced by RID. sample values: "latest", "tizen_20120101.1"
  52   --copy-kernel  copy kernel files from image /boot directory to the image output directory
  53   --runtime=RUNTIME  Specify  runtime mode, avaiable: bootstrap
  54   --install-pkgs=INSTALL_PKGS  Specify what type of packages to be installed, valid: source, debuginfo, debugsource
  55   --check-pkgs=CHECK_PKGS  Check if given packages would be installed, packages should be separated by comma
  56   --tmpfs  Setup tmpdir as tmpfs to accelerate, experimental feature, use it if you have more than 4G memory
  57   --strict-mode  Abort creation of image, if there are some errors during rpm installation
  58
  59 Options for fs image:
  60   --include-src  generate a image with source rpms included; to enable it, user should specify the source repo in the ks file
  61
  62 Options for loop image:
  63   --shrink       whether to shrink loop images to minimal size
  64   --compress-image=COMPRESS_IMAGE  compress all loop images with 'gz' or 'bz2' or 'lzo'
  65   --compress-disk-image=COMPRESS_DISK_IMAGE  same with --compress-image
  66
  67 Options for raw image:
  68   --compress-image=COMPRESS_IMAGE  compress all raw images with 'gz' or 'bz2' or 'lzo'
  69   --compress-disk-image=COMPRESS_DISK_IMAGE  same with --compress-image
  70
  71 Examples:
  72
  73  | mic create loop tizen.ks
  74  | mic create livecd tizen.ks --release=latest
  75  | mic cr fs tizen.ks --local-pkgs-path=localrpm
  76
  77 chroot
  78 ------
  79 This command is used to chroot inside the image, it's a great enhancement of chroot command in linux system.
  80
  81 Usage:
  82
  83  | mic chroot(ch) <imgfile>
  84
  85 Options:
  86
  87   -h, --help  show the help message
  88   -s SAVETO, --saveto=SAVETO  save the unpacked image to specified directory SAVETO
  89
  90 Examples:
  91
  92  | mic chroot loop.img
  93  | mic chroot tizen.iso
  94  | mic ch -s tizenfs tizen.usbimg
  95
  96 convert
  97 -------
  98 This command is used for converting an image to another format.
  99
 100 Usage:
 101
 102  | mic convert(cv) <imagefile> <destformat>
 103
 104 Options:
 105
 106    -h, --help  show the help message
 107    -S, --shell  launch interactive shell before packing the new image in the converting
 108
 109 Examples:
 110
 111  | mic convert tizen.iso liveusb
 112  | mic convert tizen.usbimg livecd
 113  | mic cv --shell tizen.iso liveusb
 114
 115 Advanced Usage
 116 ==============
 117 The advanced usage is just for bootstrap, please skip it if you don't care about it.
 118
 119 The major purpose to use bootstrap is that some important packages (like rpm) are customized
 120 a lot in the repo which you want to create image, and mic must use the customized rpm to
 121 create images, or the images can't be boot. So mic will create a bootstrap using the repo
 122 in the ks file at first, then create the image via chrooting, which can make mic using the
 123 chroot environment with the customized rpm.
 124
 125 Now mic will use bootstrap to create image by default, and to meet your requirement, you can
 126 also change the setting for bootstrap (/etc/mic/bootstrap.conf):
 127
 128 | [main]
 129 | # which distro will be used for creating bootstrap
 130 | distro_name = tizen
 131 | # which dir will be located when creating bootstrap
 132 | rootdir = /var/tmp/mic-bootstrap
 133 | # whether to enable the bootstrap mode
 134 | enable = true
 135 |
 136 | [tizen] # the supported distro for creating bootstrap
 137 | # which packages will be optional when creating bootstrap for this distro
 138 | optional:
 139 | # which packages will be required when creating bootstrap for this distro
 140 | packages:
 141
 142 KNOWN ISSUES
 143 ============
 144 Bug of latest syslinux package
 145 ------------------------------
 146 In some new Linux distributions, the "syslinux" package in their official
 147 software repositories is the version 4.04. It will cause segment fault for
 148 a fatal bug, and mic will failed with syslinux installation errors.
 149
 150 The solution is to install the patched "syslinux" package in MeeGo or Tizen's
 151 tools repos, until the official released one being fixed.
 152
 153 Failed to create btrfs image in openSUSE
 154 ----------------------------------------
 155 When creating btrfs image in openSUSE, it would hang up with showing image kernel
 156 panic. This issue impact all openSUSE distributions: 12.1, 11.4, 11.3, etc
 157
 158 REPORTING BUGS
 159 ==============
 160 The source code is tracked in github.com:
 161
 162     https://github.com/01org/mic
 163
 164 The bug is registered in tizen.org:
 165
 166     https://bugs.tizen.org/jira
 167
 168 Please report issues for bugs or feature requests.