(→Installation) |
m (s/moblin/meego/) |
||
| Line 15: | Line 15: | ||
* mic-image-creator: to create many types of images. | * mic-image-creator: to create many types of images. | ||
* mic-image-convertor: to convert a raw image or vmdk image to a live image. | * mic-image-convertor: to convert a raw image or vmdk image to a live image. | ||
| - | * mic-chroot: to provide a chroot | + | * mic-chroot: to provide a chroot MeeGo environment from a live image and translate that chroot file system into a live image. |
| - | * mic-image-writer: writes a | + | * mic-image-writer: writes a MeeGo image to a USB disk. It is a safe alternative to dd. |
The following support is provided as well: | The following support is provided as well: | ||
| Line 180: | Line 180: | ||
'''Create KVM Image''' | '''Create KVM Image''' | ||
| - | Can be used with QEMU or other VMM applications to launch | + | Can be used with QEMU or other VMM applications to launch MeeGo as a virtualized instance. |
<pre> | <pre> | ||
| Line 426: | Line 426: | ||
An option you might find useful if you're behind a firewall is the --proxy flag for the "repo" definition. You can specify it in the .ks as follows: | An option you might find useful if you're behind a firewall is the --proxy flag for the "repo" definition. You can specify it in the .ks as follows: | ||
| - | repo --name= | + | repo --name=meego --baseurl=http://repo.meego.com/trunk/repo/ia32/os/ --proxy=http://proxyhost:proxyport/ --proxyuser=proxyusername |
--proxypaswd=proxyuserpassword | --proxypaswd=proxyuserpassword | ||
If you are behind a firewall, you don't need to set proxyuser and proxypasswd, like: | If you are behind a firewall, you don't need to set proxyuser and proxypasswd, like: | ||
| - | repo --name= | + | repo --name=meego --baseurl=http://repo.meego.com/trunk/repo/ia32/os/ --proxy=http://proxyhost:proxyport |
'''Note:''' You can also insert this in your sudoers config: | '''Note:''' You can also insert this in your sudoers config: | ||
| Line 528: | Line 528: | ||
A new livecd image of meego-converted-from-raw-200902201804.iso is generated. The tool can detect the type of input image, either raw or vmdk. | A new livecd image of meego-converted-from-raw-200902201804.iso is generated. The tool can detect the type of input image, either raw or vmdk. | ||
| - | This tool is very useful. For example, the developer can launch a virtual machine running | + | This tool is very useful. For example, the developer can launch a virtual machine running MeeGo v2 and make whatever changes on the virtual system like yum install/remove a package, scp a source tarball to VM and build and try, and etc. Then with a simple "sync" or shutdown of VM, the VM image now contains his changes. With this tool, the VM image can be transformed to a live image and burned to a USB flash disk. Now developers can have final verifications in a target device, with changes in the live system. |
== Running mic-chroot == | == Running mic-chroot == | ||
Contents |
This is the main Image Creator developer's guide. For a more simplistic, step-by-step document, go to: Image_Creation_For_Beginners.
MIC is composed of a series of tools to create images and provide an easy-to-use development environment for MeeGo. MIC is based primarily on Fedora LIVE CD tools and other related open-source projects.
With MIC tools, users can create different types of images for different purposes, including live images, raw images for KVM, VMDK images for Vmware, and NAND images for NAND boot on Moorestown platforms. Also, users can use MIC tools to manipulate images like transforming an image from a virtual machine to a live image, and providing a chroot environment based on an existing live image. With these great features, developers can do development work on a host virtual machine running MeeGo or a Meego chroot environment, and transfer the resulting new live image to a target device for final debug/verification.
This document discusses only features, usage guide, and known issues.
MIC is primarily a command line utility, with a GUI that can be used on top of MIC (MIM).
MIC offers these major tools:
The following support is provided as well:
To be able to use MIC, the following packages must be available on your system. (Most of the packages are installed by default, depending on the distribution.):
You should load these modules as well, if not loaded automatically by the kernel:
Specific packages for Fedora:
Specific packages for Ubuntu 8.10:
From Binary Packages
We currently build MIC binary rpms for many popular Linux distributions. Please check here if your distribution is currently supported and available for download: http://repo.meego.com/tools/repo/.
From Stable Git Source Releases
You can get the latest stable release of MIC from the tag section in http://meego.gitorious.org/meego-developer-tools/image-creator. Click on the "Source tree" link on the top of the screen. There will be a list of tags on the right hand side.
You should follow the below steps to install it:
git clone git://gitorious.org/meego-developer-tools/image-creator.git cd image-creator git checkout 0.17 #check Gitorious for the most recent tag make sudo make install
From Development Git Tree
Note: MIC GIT tree has latest-and-greatest source, so stability is not guaranteed. If you run into errors, please use a 'Stable Release' instead before filing a bug.
You need to follow the below steps to git clone MIC:
git clone git://gitorious.org/meego-developer-tools/image-creator.git
Build and install:
cd image-creator make clean make sudo make install
Configuration of images is based on kickstart, the format used for unattended installation in Fedora and Redhat.
Super user privileges are needed. The tool is more or less self-documented, use the --help option to see options.
sudo mic-image-creator --help
KickStart (.ks) configuration files are passed to MIC to create tailored images. KickStart files specify what repos to pull from, what packages to include, what post-scripts to run and what type of images to create.
To obtain the official Meego .ks files, go here: TO-DO-LINK
Create Livecd Image
sudo mic-image-creator --config=default.ks --format=livecd --cache=mycache
This tells image-creator to use the kickstart file default.ks to obtain info about which packages to download and include in the image, and --cache is the directory on your local machine which will host a cache of these packages. The cache is very useful if you are remote to the server and reduces the amount of downloaded packages next time you create an image. Next time the command is run, this cache will simply be 'updated' if there are changes, rather than re-downloading from the repositories again.
The output of this command will be a file named meego-1.0-default-XX.iso created. This ISO image is a hybrid image and can be either written to a disk device or burned onto a cd.
To burn it onto a USB stick, just run the following command, assuming the USB stick is /dev/sdb in your system:
sudo mic-image-writer meego-1.0-default-XX.iso
Create Moorestown NAND Image
Please refer to the section dedicated to this topic below.
Create Liveusb Image
sudo mic-image-creator --config=default.ks --format=liveusb --cache=mycache
A file named meego-1.0-default-XX.usbimg will be created. To burn it onto a USB stick, run the following command, assuming the USB stick is /dev/sdb in your system:
sudo mic-image-writer meego-1.0-default-XX.usbimg
This image has a FAT file system and can be mounted easily on Windows and other OSes.
Create Liveusb Image Interactively
sudo mic-image-creator --config=default.ks --format=liveusb --interactive --cache=mycache
It directly creates a MeeGo live usb stick.
Liveusb image can be created in two different ways, interactive and non-interactive (default). When running MIC in a non-interactive mode, MIC creates a USB images file that can be copied directly into a USB stick. The non-interactive mode can be used for daily build or automated testing. The interactive mode will write the images onto a USB disk, it will detect if a USB stick is available and detects and verifies a partition is available. If two or more USB devices are present, you will be asked to select the target device. This way won't destroy existing content of USB stick unless it founds no appropriate partition, end user should use it to create live USB.
Create Loop Image
This is the simplest image format available. Such images can be loop mounted and chrooted into, for example, to build applications or for debugging purposes.
sudo mic-image-creator --config=default.ks --format=loop --cache=mycache
A file named meego-1.0-default-XX.img is created. You can use below to mount it and chroot into it.
sudo mount -o loop meego-1.0-default-XX.img /mnt sudo chroot /mnt su -
Create KVM Image
Can be used with QEMU or other VMM applications to launch MeeGo as a virtualized instance.
sudo mic-image-creator --config=default.ks --format=raw --cache=mycache
A file named meego-1.0-default-XX folder with a meego-1.0-default-XX-sda.raw image is created. For optimal results, use this feature in a machine with VT support and enable it in the BIOS.
If you use Fedora or openSUSE, run the following command to launch the image into MeeGo KVM virtual machine:
sudo qemu-kvm -m 512 -boot c -hda meego-1.0-default-XX-sda.raw -std-vga
If you use Ubuntu, run the following command launch image:
sudo kvm -m 512 -boot c -hda meego-1.0-default-XX-sda.raw
Create VMDK Image
VMDK images can be loaded into Vmware or Vmware player. MIC also generates a VMX file that has image configuration and can be used to launch the image in Vmware by just clicking the file. If you have vmplayer, it should open automatically.
sudo mic-image-creator --config=default.ks --format=vmdk --cache=mycache
A file named meego-1.0-default-XX folder with both meego-1.0-default-XX-sda.vmdk image and meego-1.0-default-XX-sda.vmx is created. Just run vmware or vmware player, and select the generated vmx file.
KickStart (.ks) configuration files are passed to MIC to create tailored images. KickStart files specify what repos to pull from, what packages to include, what post-scripts to run and what type of images to create.
For more details about the kickstart format, see http://fedoraproject.org/wiki/Anaconda/Kickstart.
Note that not all KickStart directives and options are supported for creating Meego images. MIC also adds some specific directives and options. More explained below.
The official Meego .ks files are here: TO-DO-LINK
You can download and use them as a base for the Meego images you create. Modify these .ks files as you wish to create tailored images.
Developers may want to modify the .ks files to create their own custom images. Here are the main options and sections within the .ks file.
The Meego .ks files reside here: TO-DO-LINK
You can also find in-depth .ks option information here: http://fedoraproject.org/wiki/Anaconda/Kickstart#Chapter_2._Kickstart_Options
Partition, Setup and Bootloader options
E.g.
lang en_US.UTF-8 keyboard us timezone --utc America/New_York auth --useshadow --enablemd5 part / --size 1500 --ondisk sda --fstype=ext3 rootpw meego xconfig --startxonboot bootloader --timeout=0 --append="quiet" desktop --autologinuser=meego --defaultdesktop=xfce user --name meego --groups audio,video --password meego
These are mostly self-explanatory and set up important things such as partition size, filesystem type, kernel paramters, etc. You can change these depending on what your needs are.
Repos
This is where you can specify the yum repositories that you want MIC to search and pull your packages from to make up your image. You can add official Meego repos, other remote repos, or your own local repos on your dev machine.
E.g.
# This is a comment # My first repo repo --name=trunk --baseurl=http://mytrunk.myrepo.com # My second repo #repo --name=<repo-name-2> --baseurl=< url | local-repo-dir >
NOTE: --name of the repo can be any unique alphanumeric name you give your repo, it can be anything. Just make sure you don't use the same name twice for any of the listed repos, remember they have to be unique.
To create a repo you can point to on your local developer machine, you can run the following command:
createrepo -d <local-dir>
Where 'local-dir' is a local directory on your machine that contains the rpms you want include in your local directory.
Adding Packages and Package Groups
E.g.
%packages # Example adding pkg groups @Core @X for Netbooks @Base @Development Tools @<my-PkgGroup1> @<my-PkgGroup2> # Example adding individual pkgs kernel-netbook xorg-x11-server-Xorg-setuid carrick xorg-x11-drv-evtouch <my-pkg-1> <my-pkg-2> %end
This specifies exactly what packages will be included in your image. Package groups can be specified with a "@" preceding it, as you can see from the examples above. Package groups are defined in the 'repodata' section of a repo, under a 'comps*.xml' file. Defined therein are package group names, and what packages are included in each package group. The Meego package groups are standard, and cannot be changed. You can, however, define your own package groups in your own non-Meego repos if you are using those.
Please see here for more info on defining package groups in repositories: TO-DO-LINK
You can also add individual package names to be included in the image as you can see from the second part in the above example.
Important Note about how MIC picks a package when difference version are available
A common problem is that, let's say, a packageA has more than one version residing in a repo(s) that your .ks is pointing to.
How will the MIC know which one to pick?
E.g
There exists in the repo(s) these different versions of PackageA:
PackageA-1.0
PackageA-2.0
PackageA-3.0
MIC will pick the PackageA with the highest version number (PackageA-3.0 in this case).
There is one way to get around that, and that is to set the 'Epoch' version within a package .spec file.
Example (works in both .spec and .yaml file) Name: <name> Summary: <summary> Epoch: 1 Version: <version>
MIC will first look to compare the 'Epoch' version of the packages. All Meego official packages do not include an 'Epoch' version, so if you set the 'Epoch' number within your .spec file to any positive integer, no matter if your package version is smaller, MIC will choose your package.
So back to our example.
E.g
PackageA-1.0 (Epoch not set)
PackageA-2.0 (Epoch = 1)
PackageA-3.0 (Epoch not set)
MIC will choose PackageA-2.0 in this case. And it follow that:
E.g
PackageA-1.0 (Epoch=100)
PackageA-2.0 (Epoch = 1)
PackageA-3.0 (Epoch not set)
MIC will choose PackageA-1.0.
Remember that Meego packages do not have 'Epoch' set by default, so chances are that if you set 'Epoch' in your own package to any positive integer, it will be the one MIC chooses to pull down and include in an image.
Removing Packages
If you would like to make sure that a pkg is _not_ included, you can specify that with a '-' preceding the package name.
E.g.
%packages # Example pkg groups @Core # Example adding individual pkgs kernel-netbook # Example removing individual pkgs -carrick -package-xyz %end
with the above example, packages 'carrick' and 'package-xyz' will _not_ be included in the image.
Note: all packages that depend on the package you want to remove should also be removed, or else MIC will ignore your request to remove that package from an image. E.g. if 'carrick' depends on 'package-xyz', and you specified only to remove 'package-xyz', and keep carrick, MIC will ignore the request to remove package-xyz (since carrick depends on it), and it includes both of these pgks in the image.
Post scripts
You can also specify post-scripts to be run after the image is installed.
E.g.
%post
# Example - saving some space
rm -f /boot/initrd*
rm -f /core*
# Example - Install working xorg.conf
if [ -f /usr/share/my.conf ]; then
cp /usr/share/my.conf /etc/X11/xorg.conf
fi
# Example - Tell alsa the correct audio card to use for your platform
echo -e "options snd-hda-intel index=0\noptions snd-timbi2s index=1" > /etc/modp
robe.d/alsa.conf
%end
An option you might find useful if you're behind a firewall is the --proxy flag for the "repo" definition. You can specify it in the .ks as follows:
repo --name=meego --baseurl=http://repo.meego.com/trunk/repo/ia32/os/ --proxy=http://proxyhost:proxyport/ --proxyuser=proxyusername
--proxypaswd=proxyuserpassword
If you are behind a firewall, you don't need to set proxyuser and proxypasswd, like:
repo --name=meego --baseurl=http://repo.meego.com/trunk/repo/ia32/os/ --proxy=http://proxyhost:proxyport
Note: You can also insert this in your sudoers config:
$ sudo visudo Add: Defaults env_keep += " no_proxy http_proxy ........."
so sudo will adhere to the no_proxy and proxy settings.
~/.mic2_site.conf is a configuration file that can make your life easier by specifying proxy settings, cache directories, and other variables that you normally would have to re-type in your command-line.
Below is an example you can cut-and-paste, and reuse for your needs:
[main] cachedir=/home/user1/mycache tmpdir=/home/user1/mystorage/tmp outdir=/home/user1/mystorage proxy=http://my.proxy.com:911/ no_proxy=localhost,127.0.0.0/8,.mysite.com,172.16.0.0/16
cachedir = directory where the cached repo(s) will reside. With this variable set, you do not need to pass the --cache flag in the command-line.
tmpdir = temporary directory used by mic when creating images. With this variable set, you do not need to pass the --tmpdir flag in the command-line.
outdir = where your images will reside once they are created. With this variable set, you do not need to pass the --outdir flag in the command-line.
proxy = specify your proxy if you're behind a behind a firewall.
no_proxy = specify what domains should not sure the proxy setting.
Note: When specifying proxy and no_proxy, you do not need to use the --proxy flag in your .ks files when referring to repos.
mic-image-writer writes a Meego image to a USB disk. It is a safe alternative to dd. dd is really a very dangerous tool.
mic-image-writer can run in both console mode and GUI mode. It can decide which mode to run, according to current system environment. You can also use a given option to force it to run in some other mode. Run 'mic-image-writer --help' to get usage information:
Usage: mic-image-writer [options] [image file] Options: -h, --help Show this help message and exit -c, --console Run in console mode -g, --gui Run in GUI mod
Here is a run example in console mode:
$ sudo mic-image-writer meego-xxx.img
Available usb disk:
[1] /dev/sdc: SanDisk USB Flash Drive
[2] /dev/sdb: SanDisk U3 Cruzer Micro
Please choice [1..2] ? 2
Source: /myhome/meego-xxx.img
Target: /dev/sdb
Image size: 559 MB
Estimated time: 55 seconds
Elapsed time: 64, progress: 100% 8944+0 records in
8944+0 records out
586153984 bytes (586 MB) copied, 63.0486 s, 9.3 MB/s
mic-image-writer can estimate how long it will take to write the given image to your USB disk and reports current writing progress. It automatically unmounts your USB disk, if it is mounted. If your USB can't be unmounted, it will terminate.
If you love UI mode, you can run it in X enviroment. The command with the added -g flag:
sudo mic-image-writer -g meego-xxx.img
Image name is optional.
It's very easy to use:
sudo mic-image-convertor --source-image=InputImage --target-format=Targegformat sudo mic-image-convertor -I InputImage -T Targegformat
For example, to translate a KVM raw image to livecd image, just type:
sudo mic-image-convertor --source-image=meego-core-200902200545/meego-core-200902200545-sda.raw --target-format=livecd
A new livecd image of meego-converted-from-raw-200902201804.iso is generated. The tool can detect the type of input image, either raw or vmdk.
This tool is very useful. For example, the developer can launch a virtual machine running MeeGo v2 and make whatever changes on the virtual system like yum install/remove a package, scp a source tarball to VM and build and try, and etc. Then with a simple "sync" or shutdown of VM, the VM image now contains his changes. With this tool, the VM image can be transformed to a live image and burned to a USB flash disk. Now developers can have final verifications in a target device, with changes in the live system.
There are two major usage models for mic-chroot for developers.
chroot directly into the image to use it as a development environment, then optionally create a new image based off of your changes
sudo mic-chroot -c livecd meego-core-200903131337.iso
The above command would present a chroot, using the livecd image, to developers with some bind mounts like /proc /sys /dev/pts and /parentroot. With those bind mounts, developers now can easily exchange files in chroot env with host /parentroot, and conduct yum install, yum remove and any other network related operations. After done and typing "exit", a new live ISO image is created from the chroot env with the changes developers made.
Unpack and modify the image's filesystem (which you can save), and create a new image based off of your changes
Sometimes developers want to keep the chroot env so that they can do multiple changes in that root file system at different times. So they want to execute following:
sudo mic-chroot -s my-chroot-fs --unpack-only meego-core-200903131337.iso --bind-mounts=/proc:/proc;/:/parentroot;/sys:/sys;/dev/pts:/dev/pts
The above creates a folder 'my-chroot-fs' in the current directory, using the chroot env from the livecd image. Of course if developers forget add the --bind-mounts options, they must manually do some bind mounts themselves like for /proc /sys /dev/pts to use network and run many commands. Don't forget copying /etc/reslov.conf into my-chroot-fs to use DNS. Now at any time developers think is time to create an image from the chroot env, just execute following to create a livecd image
sudo mic-chroot -c livecd --convert-only my-chroot-fs/
You need to copy a kickstart file into /root/mic2-ks.cfg which is used for automated installation of the image. To activate autoinstall mode, boot with autoinst on the command line or add --menus=autoinst to the bootloader directive in the kickstart file you use to create the image.
libgcc_s.so.1 must be installed for pthread_cancel to work" "Error: failed to create image : '/sbin/mksquashfs /var/tmp/imgcreate-FKCSsk/iso-u8xCPh/LiveOS/osmin /var/tmp/imgcreate-FKCSsk/iso-u8xCPh/LiveOS/osmin.img' exited with error (-6)
This error occurs when MIC is unable to find the proper version of libgcc. This usually happens on x84_64 systems - MIC is looking for the 32 bit version of libgcc, but only the 64 bit version is installed. Installing the 32 bit version of libgcc should resolve this.
"Error: failed to create image : '/sbin/mksquashfs /var/tmp/imgcreate-FKCSsk/iso-u8xCPh/LiveOS/osmin /var/tmp/imgcreate-FKCSsk/iso-u8xCPh/LiveOS/osmin.img' exited with error (-6)
This error can also be an issue with the syslinux package. Try updating to the latest version for your distro.
unable to remove open device
This is a race condition with device-mapper in Fedora: https://bugzilla.redhat.com/show_bug.cgi?id=506644. Usually rerunning the MIC command will resolve this.