== Developing deepOfix == To begin with, lets take a look at the deepO''fix ''directory structure. The base directory of the deepO//fix// development trunk contains the following content: bin install_cd LICENSE scripts packages packages-dev var * The ''bin'' directory contains scripts that are used to perform maintenance tasks on the deepO//fix// install CD source code. * The ''install_cd'' directory is the one that is contained on the install CD image. This directory contains all that is required on the install CD to install deepO//fix//. * The ''LICENSE'' file outlines the licensing terms of the deepO//fix// install cd source code. * The ''packages'' and packages-dev directory contains the source code, build scripts etc. for the various binary packages that are custom-built for the deepO//fix// operating system. * var contains rootfs folders and files. Further sections discuss each of these directories in greater detail. == The bin directory == Currently the ''bin'' directory contains three important scripts: * The ''mkcd'' script which can be used to create a new deepO//fix// install CD ISO image from the source code. You could then write this new image to a CD and install it. This script simply takes the contents of the ''install_cd'' directory along with the requisite boot options to generate the new CD image. To include new content to the install CD, you must add the content to the ''install_cd'' directory. * The ''update-packages'' script generates a new ''PACKAGES'' file. This ''PACKAGES'' file is required to make a valid Debian package repository on the install CD. * The ''build_rootfs.sh'' which builds the initramfs, a basic system that is used by the kernel as init These scripts were designed to automate and simplify manual and repetitive tasks related to the developing, extending and testing the deepO//fix// install CD. == The install_cd directory == This is one of the most important directories of the source code repository. It contains the layout of the on-disk filesystem found on the deepO//fix// install CD. Here is a tree of the important files and directories in this directory: install_cd/ |`- bin/ | |`- eject | |`- mdadm | `- sfdisk | |`- COPYING | |`- deepofix/ | |`- deepofix-packages/ | |`- dists/ | |`- installer/ | | |`- deepofix-installer-first-stage | | |`- deepofix-installer-second-stage | | |`- first-stage/ | | |`- second-stage/ | | `- zoneinfo | | | |`- kernel/ | `- packages/ | |`- isolinux/ | |`- LICENSE | `- tools/ === The install_cd/bin directory === This directory is meant to contain simple tools that will be used from the install CD during the process of installing deepO//fix//. All tools that exist in this directory are compiled statically to ensure that they have no runtime dependencies on shared object (''.so'') libraries. === The install_cd/deepofix/ directory === This directory is meant to contain the bulk of deepO//fix// specific install CD source code. * ''install_cd/deepofix/deepofix-packages/'' contains the compiled binary version of deepO//fix// specific packages in the Debian ''.deb'' format. * ''install_cd/deepofix/dists/'': This directory is the base of the deepO//fix// Debian packaged distribution. It contains a directory layout (and corresponding config and data files) that can be used by the Debian ''apt-get'' package management system to install packages and their automatically computed dependencies. * ''install_cd/deepofix/installer/'' contains the complete source code of the deepO//fix// installer - both the first and second stage. ** First stage installer code: ''install_cd/deepofix/installer/first-stage/'' ** Second stage installer code: ''install_cd/deepofix/installer/second-stage/'' The deepO//fix// installer is written in simple Bash shell syntax. On the deepO//fix// install CD, however, the ''ash'' shell is used; this is a simpler shell with a syntax similar to that of Bash. * The ''install_cd/deepofix/kernel/'' directory contains different versions of the Linux kernel compiled for different platforms and CPU architectures. * The ''install_cd/deepofix/packages/'' directory contains all the standard, unmodified Debian packages that are installed as a part of the deepO//fix// operating system. === The install_cd/isolinux/ directory === This directory contains all data required to boot the deepO//fix// installation CD. It includes the following important files: * The Linux kernel - ''install_cd/isolinux/bzImage'' * An initrd (initial ram disk) with a minimal root file system to start the deepO//fix// installer - ''install_cd/isolinux/initrd'' * The main ISOLINUX configuration file - ''install_cd/isolinux/isolinux.cfg'' * The pre-boot image that is displayed just after the CD has booted up - ''install_cd/isolinux/splash.lss'' == The packages directory == This directory contains the source code all deepO//fix// specific ''.deb'' packages. All these packages are generated using the [http://easysw.com/epm/ Easy Package Manager (epm)] tool. * ''altermime'' - The ''deepofix-altermime'' package that plugs into the email scanning system to optionally attach disclaimers to all outgoing email messages. * ''deepofix-mta'' - This is a virtual Debian package that ''provides'' the ''mail-transfer-agent'' package to the deepO//fix// system. This eliminates the need to have any other MTA such as ''exim'' or ''postfix'' installed on deepO//fix//. * ''djbdns'' - This is the source for the ''deepofix-djbdns'' package used to compile and install ''dnscache'', a caching, forward-only DNS server and ''tinydns'', a DNS server, along with other DNS related utilities. * ''easypush-webserver'' - This package contains the source for the [http://www.xitami.com/ Xitami Web Server] package for the EasyPush Server Manager. * ''openldap'' - This is the source for the ''deepofix-openldap'' package that installs the [http://www.openldap.org/ OpenLDAP] directory server. OpenLDAP is used for all user and group account management functions as well as for serving public addressbooks. * ''qmail-ldap'' - This is the source for the ''deepofix-qmail-ldap'' package which compiles and installs the the ''qmail-ldap'' mail server from source. * ''qmail-scanner'' - This is the source for the ''deepofix-qmail-scanner'' package which installs the [http://qmail-scanner.sf.net/ Qmail Scanner] mail scanning engine for the qmail MTA. * ''qmail-tools'' is a small collection of qmail-related tools that help in mail server administration. * ''serialmail'' is the source of the ''deepofix-serialmail'' package that is used to relay emails to users who don't exist on deepO//fix// but have accounts on a remote SMTP server. * ''services'' is the source for the ''deepofix-services'' package that installs, configures and activates various services that are run in deepO//fix// using the ''runit'' service supervision and management system. * ''squirrelmail'' - This contains the source code for the ''deepofix-webmail'' package that installs the [http://www.squirrelmail.org/ Squirrelmail] package to let users access their email from anywhere on the network. * The ''system-config'' directory stores the source code for the ''deepofix-system-config'' package. This package is responsible for a variety of system configuration and customisation * ''uschedule'' contains the source for the ''deepofix-uschedule'' package which is used for scheduling inside the deepO//fix// operating system. Now that we are done with the directory structure, lets look at how to add a particular package to deepO''fix. ''We shall use '''kvm ('''virtual machine''') '''as the platform for our test installations. Lets say we want to add a package 'test.deb' to deepO//fix//. The task of this package will be simply to print '''This is a test package''' while installation. == Creating the Package == We recommend that you refer to [http://www.debian.org/doc/maint-guide/index.en.html#contents http://www.debian.org/doc/maint-guide/index.en.html#contents] to learn how to build a package. Follow these steps to create the test.deb package. * Open a terminal. cd to any directory. * Execute the following command in the terminal: 'mkdir -p test/DEBIAN' * Execute 'vim test/DEBIAN/control'. Enter the following text in the editor: ''Package: deepofix-test '' Version: 1 Maintainer: BatMan Architecture: i386 Description: deepofix-test (for deepOfix Messaging Server) This package teaches the new born how to breathe in the deepOfix world :) Save the file. * Execute 'vim test/DEBIAN/control'. Enter the following text in the editor: #!/bin/sh echo 'This is a test package' Save the file. * Execute 'dpkg-deb test/ test.deb'. You will find test.deb in the current directory. This is the debian file we want. Now we need to add this package into deepO//fix//'s belly, so that it gets installed. Here are the steps. * cd to deepofix-trunk directory. Copy test.deb to install_cd/deepofix/deepofix-packages/ . * Now we need to add a new dependency to the deepofix-x.x.deb package. This step is necessary to ensure that test.deb is installed by apt. Go to packages-dev/deepofix . Edit DEBIAN/control. Add deepofix-test to Depends clause in the control file. Increment the version number and save the file. Execute make_deb script in packages-dev/deepofix . You will find a new deb package with a new version number. Copy this to install_cd/deepofix/deepofix-packages/ . * Now we need to make sure that the new packages' meta-data and signatures are added to appropriate files. For this we simply execute bin/update_packages. * Execute bin/mkcd. This gives us the new iso. == Running the installer == * Now that we have the new iso, lets rev it up. You need to have kvm/qemu installed for the rest of the tutorial to work. * Execute '''qemu''-''img'' create -f qcow2 test.qcow2 5G'. This creates a qcow2 image of 5G maximum size that can be used my kvm/qemu. * Execute 'sudo kvm -hda test.qcow2 -net tap -net nic'. Make sure you read some tutorial on kvm networking and set-up the same properly. The command if successfully executed, will bring up a window of the deepO''fix ''installer. Look out for the message '''This is a test package'''. If you missed it, you can boot into the freshly installed system and execute 'dpkg -l | grep test' to see that the package was installed successfully. == *Important* == * Suppose you have made changes to a few deepofix-* packages and want to re-intall the system for testing. Installing the whole deepO''fix ''system is extremely time consuming since the deepO''fix ''specific packages are installed in the second stage, after the first stage is over. The first stage consists of installation of debian base packages which takes some time. A better way is to use the -loadvm -savevm features of kvm/qemu.