What follows is a correction to spelling and grammar for the file "building" that is included in the file devel-colinux-20070302.tar.gz (\devel-colinux-20070302\doc\building).
Please have a copy of that document before you go writing anything on this page.
This page is for correcting THAT PARTICULAR document and not for adding the latest and greatest ideas known to mankind. The premise of this page is to fix the explanations given in that document so the translation to English does not cause someone to compile coLinux incorrectly.
I (the author of this page) do not neccesarily agree with everything on this page. I am only correcting the English of an existing translated document that was not as precise as it could be. Thanks go to the great author's whose spelling I am fixing. They know more English that I do of their languages.
Building Cooperative Linux Dan Aloni, da-x at colinux.org ================================================================= Table of Contents 1. Prerequisites 2. Build systems 3. configure && make && make installer 3.1 configure 3.2 make download 3.3 make 3.4 make package 3.5 make installer 3.6 make clean 3.7 make disclean 3.8 Comments about configure system 4. Building a coLinux kernel 4.1 Kernel build Dependencies 4.2 Compiling the Cooperative Linux kernel (the vmlinux file) 4.3 Testing new kernel builds 4.4 Private kernel config 4.5 Add private kernel patches 5. Compiling the OS support code 5.1 OS build Dependencies 5.2 For Microsoft Windows as host 5.2.1 Complete downloading and build for Win32 under Linux (MinGW32) 5.2.2 Running the compiling script 5.2.3 Create a pre-distributable package as ZIP 5.2.4 Source tree example for a MinGW build process 5.3 For Linux as host 5.3.1 For Linux as host with different libraries (patched FLTK) 6. Create, resize and optimize images ================================================================= 1. Prerequisites ---------------- When compiling coLinux to run on Linux of the same architecture, only one compiler needs to be used. For cross compiling, the components that comprise coLinux need to be compiled using 2 differently targeted versions of GCC (http://gcc.gnu.org/). One gcc is required for the native Linux architecture that coLinux is designed to run on (i686-pc-linux), and the other version is used to compile binary executables and drivers for the host OS (i686-pc-mingw32). Please note that the newest version of gcc uses --target=i686-pc-linux-gnu and not --target=i686-pc-linux . You could run ./config.guess to find the correct name for --host but it is not correct to specify --host since it should be guessed correctly (by ./config.guess script). You should not specify --target if it is the same as --host when using the newest gcc. So never use --host or --target unless you must (EG: when cross-compiling or making a canadian-cross (when --host, --build and --target are !=)). The versions of the two compilers need to match as closely as possible. Versions 2.95.x, 3.1.x, 3.2.x and 3.3.x of gcc are not guaranteed to be ABI-compatible. If the compiler used for building the kernel and the daemons doesn't have the same version, you can't run coLinux. The daemon blocks this. To resolve these problems, you should always build the Linux cross-compiler (i686-pc-linux-gnu) and the Win32 compiler (i686-pc-mingw32) from the same set of Gnu gcc sources and put it first in the search PATH. You can set the variable 'COLINUX_GCC_GUEST*' in bin/*.cfg. The scripts build automaticaly and use the specified compiler. This feature can be enabled using the option --gcc-guest-build in "./configure". 2. Build systems ---------------- The coLinux source tree contains different types of build systems. The simplest is a "./configure && make". This should be used if you are a new coLinux devoloper and want to build coLinux binaries from source for the first time. The ./configure script is not the same as in other software projects. This script does not detect all the needed tools and host environments. It creates a simple configuration to make it easy to have "standard" Linux projects using "./configure && make". This should help newcommers to compile coLinux. Later you can run some of the scripts in bin directory by hand. For example, you want only to rebuild the kernel, then run "cd bin; ./build-kernel.sh". All scripts in the bin dir use settings from the main "./configure" script. The usual situation is to rebuild the kernel without building the complete coLinux (daemons). You do not need a cross platform for this step, so we describe it, in this guide, in the step "Build non standard Linux kernel", "4.2 Compiling the Cooperative Linux kernel (the vmlinux file)". The texts are sometimes not up to date. You should know something about building the kernel, patching and in general, using the gcc toolchain. The source tree uses a Python build system to manage out-of-date sources and allow for building different targets (WinNT and Linux) without using "make clean". The Python build system starts with "make colinux" in the src directory and needs various environment settings to be setup beforehand. We suggest you start with "configure && make". When you are more familiar with how coLinux is built you can try to use the shell scripts from the bin directory. 3. configure && make && make installer -------------------------------------- 3.1 configure Call './configure' in the toplevel directory to create the file bin/user-build.cfg using the absolute paths of your installation. Default target is WinNT. There are some options that can be used to override the default directories. Run './configure --help' for a list of options. Example for WinNT as host (default): ./configure --target=i686-pc-mingw32 \ --downloaddir=$HOME/colinux-devel/download \ --prefix=$HOME/colinux-devel/mingw32 For Linux as host you must use the option '--target=i686-pc-linux'. Host kernel directories will be detected automaticaly. You can alter them by using --hostkerneldir. Example for Linux as host: ./configure --target=i686-pc-linux \ --downloaddir=$HOME/colinux-devel/download \ --targetkerneldir=$HOME/colinux-devel/download/linux-2.x.y --hostkerneldir=/usr/src/linux 3.2 make download 'make download' is optional. It downloads all missing source files. 3.3 make Call 'make' in toplevel directory (not in src/) to build all cross tools, cross compiler, libraries and target. Makefile is only a wrapper for bin/build-*.sh scripts. Settings in bin/user-build.cfg are used by Makefile and a lot of other shell- and Python- scripts. Missing source files will be downloaded with wget. To detect 'out of date' files this Makefile does not timestamps. Subversion checkout (or download) can not handle timestamps. So we use md5sum to check out new sources, patches or configuration. After every compile it updates the md5sum file at the end. Run "make help" to see what "make all" will build, if you do not give a target. 3.4 make package 'make package' will copy executables as ZIP file on dist directory. 3.5 make installer 'make installer' builds the complete coLinux installer. This needs wine, "makensis" and more win32 installer tools. 3.6 make clean This will only cleans the source tree of coLinux daemons. The cross tools and libraries are untouched. 3.7 make distclean This will also remove control files for md5sum, user-build.cfg and libraries. But it will never remove your cross compiler (we hope, you have not installed it under the coLinux source tree). After this step you must run './configure' again. 3.8 Comments about configure system This version of configure is provided only with the targets i686-pc-mingw32 or i686-pc-linux. No other strings supported. (Sorry, configure is very simple.) Some build steps are supported by a separate call. For example to compile coLinux daemons without building the kernel: 'make colinux'. Optional targets can be listed with 'make help' 4. Building a coLinux kernel ---------------------------- 4.1 Kernel build dependencies You can check the gcc version that was used to build your coLinux by typing "dmesg | head -n1", this would print text like: "gcc version 3.4.5". In that case you need a gcc version 3.4.x, check it by running "gcc --version". If you do not have it try "apt-get install gcc" to install it. If you do not have such packet to install, probably you need to build gcc yourself from source. The script bin/build-cross.sh does it, if you have ran "./configure". The default gcc version is defined in the file bin/build-common.sh. You can only change it, if there exists a MinGW version of this gcc. After changing it, you also need to rebuild the cross gcc and all daemons. We suggest you not change the gcc version to an older version. Read the coLinux changelog (inside Subversion) about the problems with older gcc versions and the fixes. If you are up to it then compile gcc-4.2.0 for MinGW and Linux. Since coLinux version 0.7.2 the gcc dosn't longer depends on one major gcc version. The ABI is runtime checked and inside the building now. This opens more gcc versiond for kernel builds (tested from 3.4.x up to gcc 4.3.0). Usebility of installed gcc can check with "./configure --no-create". 4.2 Compiling the Cooperative Linux kernel (the vmlinux file) Unpack the source tarball of coLinux. Locate the file series-2.6.17 in the directory patch/. This file give you the supported kernel versions. (version 2.6.17 for instance, can be obtained from www.kernel.org) Unpack the kernel tar in home directory. Make sure that the directory of the Linux kernel is named 'linux-2.6.17'. Apply the patches found in the series file to the Linux kernel as exactly in this order. If conflicts arrise, then it is possible that there is a mismatch between the version of the kernel and the version that the patch is designed to apply to. Series file was handled by quilt. You can create a single patch file of all the pathes, than you can use this summary file for patching the kernel source. Simply cat all files to one file. Locate function "patch_kernel_source" from bin/build-kernel.sh, to find more examples for patching kernel and the quilt handling. For example: ~/# cd PathToColinux/patch ~/PathToColinux/patch# cat `cat series-2.6.17` > /tmp/sumary.patch ~/PathToColinux/patch# cd ~/# wget http://www.kernel.org/pub/linux/kernel/v2.6/linux-2.6.17.tar.bz2 ~/# bunzip2 -dc linux-2.6.17.tar.bz2 | tar x ~/# cd linux-2.6.17 ~/linux-2.6.17# patch -p1 < /tmp/sumary.patch ~/linux-2.6.17# rm /tmp/sumary.patch The coLinux package is supplied with a premaid Linux kernel configuration file. Copy it to your kernel tree: ~/linux-2.6.17# cp PathToColinux/conf/linux-2.6.17-config .config Append coLinux version information to kernel version name: ~/linux-2.6.17# echo "-co-0.8.0" > localversion-cooperative Update config and build vmlinux: ~/linux-2.6.17# make oldconfig ~/linux-2.6.17# make vmlinux Module build and install: ~/linux-2.6.17# make modules ~/linux-2.6.17# su -c "make modules_install" 4.3 Testing new kernel builds Then test to run this unchanged kernel with your daemons. Be sure to save all your work and the disk cache, before you run your new kernel. On windows, only a reboot save the disk cache. I suggest you reboot windows _before_ you start the new kernel! After these steps you can modify kernel config or add some special patches and rebuild your special kernel. 4.4 Private kernel config After the default kernel is working, you can call "make menuconfig" to change your options. If you have X11 try "make xconfig" or "make gconfig". You need to have installed (on coLinux) the packages gtk+-2.0 glib-2.0 libglade-2.0 for xconfig and install qt-mt for gconfig. It is a bit of work but it looks good! Typing "make menuconfig" runs: "scripts/kconfig/mconf arch/i386/Kconfig" Typing "make gconfig" runs: "scripts/kconfig/gconf arch/i386/Kconfig" Typing "make xconfig" runs: "scripts/kconfig/qconf arch/i386/Kconfig" The program "mconf" is a curses graphics interface both gconf and qconf use X11. The qconf program saves it's setting (both X11 settings, EG: window size and position and qcon settings, EG: wide of the individual panes and "show options") but (as least for me, and I think I set it up correct) the gconf program does NOT save these settings. The gconf program seems to have a few more buttons to push than the qconf program does and both (sometimes) show features differently than mconf. This might be due to a bug in reading .config or simply my lack of familiarity but I like to use mconf first (for it's simple run through of everthing) and then go back and re-check with gconf to get a graphical presentation of the choices I made and fix any of (my) mistakes. It is very easy with either gconf or qconf to click from one section of settings to another to check (or change) options that interfere (or need) another option to work properly (or change what extra choices you have). It is more difficult with mconf to cursor-key back and forth between the options and get things set properly - so make (and use) both types :( . When I built gconf it seemed unable to alter _some_ features (that were NOT disabled) but did work to alter other features. Maybe something is not working with the linux-2.6.17 kernel's version of gconf. With gconf when I changed the setting for "show all options" the screen did not update immediately, I needed to click a "screen-layout-button" and then go back to the prior layout to refresh the screen. This does NOT happen with qconf, it updates the screen immediately. I suspect qconf is working better than gconf (but it _might_ be the way it was installed - I used the standard method to install, so it is not my fault). WARNING: Don't enable device drivers with direct hardware access (ISA-, PCI- or VL-Bus) and don't change cpu specific configs. This will likely crash your system. Now run "make vmlinux modules" in the kernel source again and test it. Save the file ".config" as your new default config in coLinux source tree as conf/linux-2.6.17-config. 4.5 Add private kernel patches Start from a clean build of kernel and test it, before you change any kernel source. Patching in your additional patch, use option --dry-run for testing. After your additional patch is clean or only some minor are wrong, you can run patch without --dry-run. Watch for *.rej files. If they exist, add the non patched lines by hand to the listend files. Than create a fixed diff from the *.orig file. Replace wrong parts in your additional patch with the fixed diff parts. Edit the series file in patch directory and add your new patch file at the end. Better way is, to use "quilt import" for your patch files. Run the "make oldconfig", answer for the new devices with the right option. If you are unshure, use 'N'. Save the file ".config" as your new default config in coLinux source conf/linux-2.6.17-config. Run "make vmlinux modules" and check the new nernel. 5. Compiling the OS support code -------------------------------- Compiling the operating system dependent support code is a little more complex. The current build system assumes a cross compiler toolchain is installed for that purpose. This is the second way to compile coLinux, it's more flexible. But you need to setup all the paths and tools by hand. These steps are for devolopers with more background. 5.1. OS build Dependencies Cross platform * MinGW (version 3.x) The coLinux console depends on: * FLTK (major version 1) Python build system * Python interpreter 2.3 or grater 5.2 For Microsoft Windows as host 5.2.1 Complete downloading and build for Win32 under Linux (MinGW32) To compile source for a Windows target, the compiler must be self compiled for this target. You can not download a binary of this compiler! This needs a Compiler, devel-libraries and a lot of tools: (Versions from my installation. Others works also, ./configure checks it.) bison-1.75 need by binutils (yacc 91.7.30 have error YYEMPTY) flex-2.5.4 need by binutils (arlex.l: Permission denied) gnu/gcc 3.4.5 for building guest kernel binutils 2.16.91 for building guest kernel make-3.80 module-init-tools-0.9.14 patch-2.5.9 python2.3 for coLinux build system, need version 2.3+ texinfo-4.5 need by binutils unzip-5.50.0 extracting winapi source wget-1.8.2 download source files zip-2.3 packing pre releases glibc-devel ncurses-devel ... and many more devel packets ... Create a new directory, extract coLinux source in this directory, set scripts executable and ran the download script in "bin" directory. mkdir $HOME/colinux-devel cd $HOME/colinux-devel tar xzf colinux-20061210.tar.gz cd colinux-20061210/bin chmod +x *.sh ./build-all.sh --download-only Files will be downloaded into directory $HOME/colinux-devel/download. 5.2.2 Running the compiling script Edit bin/user-build.cfg and set some directories. It's unsafe to use a relative path in this build script. The BINDIR is mostly the bin directory, but not in all cases! build-all.sh --download-only Download all missing files, step is optional build-all.sh Extract (OVERWRITE!) and compile all files build-cross.sh Extract and compile the cross compiler build-colinux-libs.sh Extract and compile all libs build-kernel.sh Extract, patch, compile the kernel and modules build-colinux.sh Recompile only the coLinux daemons and console ! Any starts of build-kernel.sh will delete all source and extract it again ! ! If you have changed some kernel sources, set COLINUX_KERNEL_UNTAR="no" in ! ! the file bin/user-build.cfg do save your work. Or call "make menuconfig" ! ! and "make vmlinux" into kernel directory manually ! build-all.sh is a complete build process for binutils, cross compiler, libraries, kernel and colinux daemons. (~40 Minutes on 1.8MHz Pentium) The build process based on build-all works completly at top-level directory colinux-devel. The cross-compiler was also installed in users directory (not system wide). We never need root rights for installing headers, libs or programs. After Downloading a new version of coLinux source, should only extract source at same top level directory and run the last scripts build-kernel.sh and build-colinux.sh. In some cases you might also need to compile the libs. The cross compiler mostly never need compile again. The work of build-all is controlled by md5sum of some sources and some target files. Md5sum is updated after build step was complete and stored as .build-*.md5 in 'BUILD' directory. An "error on MD5" is not a file error here, it's only a detection for outdated sources, where need to rebuild. Call as 'build-all.sh --rebuild' will ignore md5sum and builds all cross tools, cross compiler, libraries and target files again. Single script can also use to recompile one step. For instance you can rebuild the win32k-api and fltk library by calling 'cd bin ; ./build-colinux-libs.sh' 5.2.3 Create a pre-distributable package as ZIP Run the common script to create a zip archives in directory 'dist' with all executables for Windows host: . ./build-common.sh ; build_package The target files should copy into a Windows host system, unpack the zip files and installing or update the coLinux driver with these commands: cd OldColinuxPath colinux-daemon.exe --remove-driver cd NewColinuxPath colinux-daemon.exe --install-driver 5.2.4 Source tree example for a MinGW build process Source tree before building, after download: /colinux-devel +-- colinux-20061210/ | +-- bin/ | | +-- build-all.sh (Compile for Win32, | | ... download missing files) | +-- src/ | ... ... +-- download/ +-- binutils-2.16.91-20060119-1-src.tar.gz +-- colinux-20061210.tar.gz +-- fltk-1.1.6-source.tar.bz2 +-- gcc-core-3.4.5-20060117-1-src.tar.gz +-- gcc-g++-3.4.5-20060117-1-src.tar.gz +-- linux-2.x.y.tar.bz2 (version of coLinux kernel) +-- mingw-runtime-3.9.tar.gz +-- w32api-3.5-src.tar.gz +-- w32api-3.5.tar.gz +-- wpdpack_3_1.zip Source tree after building cross compiler and coLinux binaries: /colinux-devel $USER_TOPDIR +-- colinux-20061210/ | ... Colinux sources +-- build/ $BUILD_DIR | +-- binutils-2.16.91-20060119-1/ (cross working dirs, | +-- fltk-1.1.4/ deleted after build) | +-- gcc-3.4.5-20060117-1/ | +-- w32api-3.5/ | +-- wpdpack/ | +-- linux-2.x.y-source/ $COLINUX_TARGET_KERNEL_SOURCE | | ... kernel sources | +-- linux-2.x.y-build/ $COLINUX_TARGET_KERNEL_BUILD | ... kernel building dir | +--_install/ $COLINUX_TARGET_MODULE_PATH | +-- lib | +-- modules | +-- 2.x.y-co-0.8.0/ | +-- kernel/ | | +-- ... Some modules.ko ... | +-- modules.dep +-- dist/ $COLINUX_INSTALL_DIR | +-- daemons-0.8.0.zip (Binaries for target) | | +-- colinux-console-fltk.exe | | +-- colinux-console-nt.exe | | +-- colinux-daemon.exe | | +-- colinux-net-daemon.exe | | +-- colinux-*.exe (Some more coLinux daemons) | | +-- linux.sys (Windows coLinux driver) | +-- vmlinux-0.8.0.zip | | +-- vmlinux (kernel) | +-- modules-2.x.y-co-0.8.0.tgz (Modules for target kernel) +-- download/ $SOURCE_DIR | ... Source files ... (source store here) +-- log/ $COLINUX_BUILD_LOG | +-- build-colinux-$$.log (Logfiles of build process) +-- mingw32/ $PREFIX +-- bin/ | +-- i686-pc-mingw32-gcc | ... Cross compiler binaries with prefix 'i686-pc-mingw32-' +-- i686-co-linux/ | +-- bin/ $COLINUX_GCC_GUEST_PATH | | +-- i686-co-linux-gcc | | ... Compiler for kernel build with prefix 'i686-co-linux-' | +-- i686-pc-linux-gnu/ | | +-- bin/ | | +-- gcc | | ... Compiler for kernel build without prefix | +-- include/ | +-- info/ | +-- lib/ (for Linux as host) | +-- libstdc++.so.6.0.3 | +-- libstdc++.a | ... Linux libraries for this compiler | +-- man/ | +-- share/ +-- i686-pc-mingw32/ | +-- bin/ | | +-- gcc | | ... Cross compiler binaries without prefix | +-- lib/ | ... Cross compiler static libraries (e.g. libfltk.a) ... +-- include/ +-- info/ +-- lib/ +-- man/ +-- share/ 5.3. For Linux as host For building and runnning coLinux on Linux you need: 1. Tree or headers of the designated host kernel available, in order to build the kernel module (colinux.ko). Currently works only with host kernel 2.6.x, tested up to 126.96.36.199, 2.6.10 - 2.6.18. 2.6.19 as host kernel is not usable. Host kernel should not set CONFIG_REGPARM, coLinux can't run there. >=2.6.20: "-mregparm=3" in arch/i386/Makefile is badly idea for coLinux. 2. patched fltk-1.1.6 (see patch directory) installed in the system (./configure ; make ; su -c "make install") You can also install this version under your HOME (see below). 3. Properly set the environment variables (e.g.): export COLINUX_TARGET_KERNEL_PATH=/path/to/your/patched/colinux/kernel/tree export COLINUX_HOST_KERNEL_DIR=/path/to/your/host/kernel export COLINUX_HOST_OS=linux And run make in the 'src' dir. Running it is quite simple. For example, consider these list of files: -rwxr-xr-x 1 root root 566805 Jun 21 13:02 colinux-console-fltk -rwxr-xr-x 1 root root 289478 Jun 21 09:58 colinux-daemon -rwxr-xr-x 1 root root 107509 Jun 21 09:58 colinux-net-daemon -rwxr-xr-x 1 root root 115637 Jun 21 13:02 colinux-serial-daemon -rw-r--r-- 1 root root 341519 Jun 21 13:02 colinux.ko -rw-r--r-- 1 root root 399 Jun 5 18:17 colinux.cfg -rwxr-xr-x 1 root root 2614823 Jun 21 13:02 vmlinux The steps are basically: xhost + su insmod colinux.ko PATH=.:$PATH colinux-daemon @colinux.cfg This much like the Windows port except where the logic around the installation of the driver is more simple. You should run coLinux in a graphic environment, KDE, Gnome or after 'startx'. 'xhost +' allows root (su) to use your user desktop (access control disabled). PATH=.:$PATH is needed, if the executables aren't installed in your e.g /usr/local/bin or elsewhere in $PATH. 5.3.1 For Linux as host with different libraries (patched FLTK) - Patch and build fltk from source cd /tmp tar xjf fltk-1.1.6-source.tar.bz2 cd fltk-1.1.6 patch -p1 < colinux-source/patch/fltk-1.1.6-linux-patch.diff ./configure --prefix=$HOME/i686-pc-linux-local make -C src make -C src install make -C FL install cd /tmp rm -r fltk-1.1.6 - Run coLinux configure with path to this fltk cd colinux-source export PATH=$HOME/i686-linux-local/bin:$PATH ./configure --target=i686-pc-linux ... - Run coLinux build with path to FLTK libraries export COLINUX_TARGET_KERNEL_PATH=/path/to/your/patched/colinux/kernel/tree export COLINUX_HOST_KERNEL_DIR=/path/to/your/host/kernel export COLINUX_HOST_OS=linux export COLINUX_CFLAGS="-I$HOME/i686-pc-linux-local/include" export COLINUX_LFLAGS="-L$HOME/i686-pc-linux-local/lib" make HOSTOS=linux colinux 6. Create, resize and optimize images ------------------------------------- Mostly images are created from minimal distribution installation under Qemu. From Qemu-image should use the option "offset" for loop mount. Tips for cleanup the image: - Run "apt-get clean" on Debian to remove all downloaded files. - Remove files /lib/modules/*-co-* /boot /var/log/*.gz /var/run/*.pid - Clean files in /var/log (don't remove files! Set the size to zero.) Final clean and resize the image: - You should have an image file, named "image.old" here - Create an new empty file. This is the best to compress it very small. Use your favorite size as count. Blocksize is 1MB, the count=1024 in the example creates a file with size of 1GB. Increase the count for bigger images. dd if=/dev/zero of=/tmp/image.new bs=1M count=1024 For coLinux version >= 0.7.1 the old and new image files can live on "cofs" mounted file system. That means, you can create the new image directly in your Windows filesystem (... of=/mmt/cofs-Windows/image.new ...). - Create a filesystem on the new file mkfs.ext3 /tmp/image.new - Mount new and old images mkdir /tmp/new mount -o loop /tmp/image.new /tmp/new mkdir /tmp/old mount -o loop,ro /tmp/image.old /tmp/old - Copy all files from old current image into the new image. cd /tmp/old cp -ax * /tmp/new/ cd /tmp - Unmount images umount /tmp/new umount /tmp/old - Check and cleanup file system fsck.ext3 -f /tmp/image.new - Disable time based "Check interval", set more mount counts tune2fs -i 0 -c 60 /tmp/image.new CoLinux version 0.6.4 counts +2 per boot with initrd, the default 30/2 would be very often check the file system on boot. - Compress this image bzip2 </tmp/image.new >/tmp/image.bz2 - Test the /tmp/image.new on coLinux now. If it fails, repair it and repeat the steps from beginning