root/morphix/trunk/how_tos/morphix_docbook.txt

////////////////////////////////////////////////////////////////////////////////////
This file is used to generate the morphix_docbook.xml
Edit this file!
  docbook_html/prepare_html.sh 
  Is used to make the xml and html

Try not to use :-
Yes :- acsciidoc -> xmlto does no work with ':-' 
////////////////////////////////////////////////////////////////////////////////////

Morphix Manual
==============
www Morphix Org
v0.5, September 2006
:Author Initials: BMS

Dedication
----------
To our benevolent dictator Alextreme, Debian and everyone at #morphix


Preface
-------
This is an attempt to document some of ways to use Morphix. In particular to support a new Morphix LiveCD - MorphingMorphix.

indexterm:Knoppix-Hacks[Knoppix Hacks]
The following is an extract from Knoppix Hacks - 100 Industrial-Strength Tips and Tools describing Morphix.

A look at Morphix: The Hack-friendly Live CD
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Given the popularity of Knoppix and the vast amount of people
working on derivative versions of Knoppix, it doesn't come as a
surprise that people have been working to make Knoppix easier to
modify and more flexible to use. In early 2003, Morphix was born out
of a number of Knoppix remasters' wishes to have a version of Knoppix
that was good at what they used Knoppix for: a base upon which to
build their own versions using Debian GNU/Linux.

What makes Morphix so special compared to other Live CDs
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

As you have seen in this book, there are a number of ways to change Knoppix to
your liking. However, these possibilities have always been, and probably always
will be, fairly limited. Knoppix was made for different goals: to detect your
hardware as fast and correct as possible, to be a good demonstration of Linux
and to include as much common-use Linux software as
possible. Morphix's goals however are different: Ease of
customization, ease of use, ease of installing. We are a lazy bunch,
but thanks to Klaus Knopper we had a solid place from which to work from.

Knoppix, and most Knoppix\' derivatives, are fairly monolithic in
nature: They are essentially complete ready-made filesystems all
compressed into one file. Morphix on the other hand is built up around
the idea of modules: you have one module that boots your live CD and
detects your hardware, another that contains your live CD filesystem
and zero or more extra modules that can contain minor or major changes
and additions to the system. This way, Morphix promotes the reusing of
smaller, existing modules instead of one large /KNOPPIX/KNOPPIX
file. Complicated? Well, a look at a typical Morphix live CD might
help. This is the structure of Morphix 0.4-1 LightGUI, one of the
Morphix flavours:

'<pre>'
'/base/boot.img'
'/base/morphix'
'/mainmod/MorphixMain-Light.mod'
'</pre>'

While it seems quite empty, this is how we release typical versions
of Morphix. They are quite bare but offer users (or \'morphers\', as we
call ourselves, as you will notice we have a strange lingo for the
uninitiated) more possibilities to change the resulting live CD. We
will take a closer look at these and other tricks in the hack \"Morphing
Morphix\" later on.

Morphix currently has four ready-to-burn \"combined ISOs\" available for
download and a list of extra modules available for whomever needs
them. All combined ISOs contain the Morphix installer, a graphical
tool for installing Morphix onto your harddisk, and a number of
other graphical and command line Morphix tools for various
purposes. Each of these live CDs has their own targeted audience--our
opinion has always been that we should offer (limited) choice to users
and as much choice as possible for developers:

Morphix LightGUI
^^^^^^^^^^^^^^^^
Aimed at lower-end PCs, LightGUI features the XFCE4 desktop and
contains a reasonable amount of lighter tools. It was the initial
version of Morphix, and the aim has been to keep LightGUI small enough to
have it fit on 210MB CDR(W). LightGUI includes Abiword, Gnumeric, Dillo and
Firefox. For communication, Gaim and Xchat are included, and for
photo processing the GIMP has been added.

Morphix Gnome
^^^^^^^^^^^^^^
Formerly named Morphix HeavyGUI, this flavour was for some time the
only conterpart of LightGUI. Including Gnome, OpenOffice.org, 
Mozilla, and the kitchen sink, Morphix Gnome was aimed at office users
with more recent machines. Even so, a normal Morphix Gnome ISO still
doesn't fill up the whole (650MB) CD-ROM, and recent versions weigh in at
around 500MB.

Morphix KDE
^^^^^^^^^^^
Although primarily focused on GTK/Gnome, the Morphix crew acknowledges
that users might prefer KDE instead (and looking at the number of
derivatives, a lot of users do!). Morphix KDE contains the whole KDE suite of
programs, as well as Mozilla and other applications. Morphix KDE
sits inbetween LightGUI and Gnome when it comes to size, and fills up
approximately 400MB of space on your CD-ROM.

Morphix Game
^^^^^^^^^^^^
An odd-ball in Morphix, this flavour contains the very light IceWM and
a very large number of Open Source games. BZflag, Frozen Bubble, Freecraft
and many, many others are sure to entertain the kids (or entertain the
kid in you) for quite a few hours. Normally Morphix Game also includes
one or more demo versions or free full versions of commercial Linux
games, adding to the fun. Gaming on Linux a rarity? This hasn't been
the case for many years, no matter what kind of games you enjoy!

All the official Morphix live CDs contain the Morphix installer, as
stated above. This tool allows users to easily install their Morphix
(or derivative) live CD onto a hard disk. Often overlooked, the
difference between a live CD and a hard disk install is very small
indeed. The Morphix installer is also built in a flexible manner so
that derivatives can even rebrand the Morphix installer, although the
source itself is licensed under the GNU GPL. A graphical partitioner
and series of configuration tools have been under development and are
likely to be part of Morphix by the time this book comes off the press.

Morphing-Morphix
^^^^^^^^^^^^^^^^
The purpose of 'Morphing-Morphix' is to provide the quick way to start 'Morphing' and making your own LiveCD. Just boot the CD and start Morphing, no need to install tools, compile applications or switch operating systems. All is required is some space on a connected hard drive. The aim is to be able make new Morphix LiveCDs using this LiveCD, as an introduction to Morphix. In fact this LiveCD was made using Morphing-Morphix.

Derivatives
^^^^^^^^^^^
A lot has been said about the number of Linux distributions recently. What
others see as a complicated mess, we see as a healthy, messy
eco-system. Morphix has quite a few offspring
and a lot of them are specially focussed at a single group of people
(ranging from Brazilian engineers, non-profit organizations or
self-proclaimed Hackers) or are providing a localized non-English
Linux distribution (ie. Chinese, Galicia/Spanish, Hindi, Arabic), the list
goes on and on. So, if the default Morphix Live CDs aren't to your
liking take a look on www.morphix.org for a list of related
projects. Even if you start \'morphing' from one of these derivatives,
you can be sure of a base to fall back to and a design that will get
your project \'live\' and updated ASAP.

Happy Morphing!


Morphix ISO README
------------------
If you're wondering what the directories on the cdrom do, this is the right 
document. If not, take a look on morphix.org! (don't miss the FAQ or wiki) 

indexterm:boot[boot]
'o /boot'  + 
        contains the init ramdisk, grub menu and kernel

indexterm:base[base]
'o /base'  + 
        contains morphix, the module that detects/configures your hardware and
        contains your standard kernel modules. 

indexterm:mainmod[mainmod]
'o /mainmod' + 
        contains mainmodules, these are also cloop images, comparable to
        the /base/morphix file, but using a different structure
        see README.mainmod for info about the internal structure of these files
        In short: mainmodules contain your filesystem, except for your kernel,
        loadable kernel modules, and hardware detection scripts.

indexterm:minimod[minimod]
'o /minimod ' + 
        contains minimodules, again these are cloop images.
        You don't need them, but you can add extra functionality by including
        extra minimodules. See README.minimod.

indexterm:exec[exec]
'o /exec ' + 
        If you place files in this directory, they will be executed at
        boottime. Note that this does not mean that programs using X
        will be executed, the proper way would be to add a line to .xinitrc
        for this. Place the following in /exec/script.sh for example: + 
          'echo \"program\" >> /home/morph/.xinitrc'
          'echo \"program\" >> /home/morph/.xsession'
        (Does Debian still use .xsession? not 100% sure, xinitrc should 
        be enough...)
        Again, try this out. Exit from X, execute the script, and 
        \'sh /morphix/init.sh\'

indexterm:copy[copy]
'o /copy' + 
        If you place files in this directory, they will be copied over to the
        root of your filesystem. Use directories to place files in a certain
        directory instead. For example, have: + 
          '/copy/home/morph/.xfce4/xfcerc'
        to copy the xfcerc file to /home/morph/.xfce4/xfcerc at boottime.
        
        Interesting things can be done with adding files to locations like: + 
          '/copy/morphix/init.sh'
        or
          '/copy/morphix/loadmod.sh'

        as these files are executed after being swapped. Great fun ;)


Fast Introduction to building your own Morphix based livecd
------------------------------------------------------------

Really Fast Introduction
~~~~~~~~~~~~~~~~~~~~~~~~

* Get a Morphix Base iso
* Add "deb http://www.morphix.org/debian ./" to your /etc/apt/source.list
* apt-get update ; apt-get install morphing-tools
* Edit mymainmod.xml
* mmaker mymainmod.xml myprograms.mod
* make-iso /path/source myfirstlivecd.iso

Fast Introduction
~~~~~~~~~~~~~~~~~

Foreplay
^^^^^^^^

* Use a Debian based Linux distro [preferably Debian sid, aka unstable, but every recent one should do]
* Get a morphix based .iso [or better: just a base .iso, preferably a stable one atm, like 0.5-pre5 or an autobuilded base .iso]
* Open a root terminal [su -, you get the point]
* mount -t iso9660 -o loop nameoftheisoyoudownloaded.iso /mnt/whatever
* cp -a /mnt/whatever/* /path/to/the/extracted/stuff [like /scratch/iso]

Setting up the build environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

* Add "deb http://www.morphix.org/debian ./" to your /etc/apt/source.list
* apt-get update
* apt-get install morphing-tools

Creating your own mainmodule
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

* See this manual about mmaker for building an .xml file describing your mainmodule, which will basically be your system
* If you're done with the .xml file [e.g., mymainmod.xml], type "mmaker mymainmod.xml myprograms.mod" or whatever you like to name them

Building an .iso out of it
^^^^^^^^^^^^^^^^^^^^^^^^^^

* Now, remove the files in /scratch/iso/mainmod
* Copy/move your myprograms.mod into /scratch/iso/mainmod
* make-iso /scratch/iso myfirstlivecd.iso
* Done. Burn to cd with your favorite burn program or run with "qemu -cdrom myfirstlivecd.iso" in the qemu emulator, for example

More advanced stuff
^^^^^^^^^^^^^^^^^^^

If you manually modify some stuff in /tmp/libmorphix-<randomsequence> (e.g., /tmp/libmorphix-9oVKWq) , you have to use the following command to recompress the mainmod: "module-builder /tmp/libmorphix-9oVKWq aquamorph_20051120a.mod" (or whatever you want to call the mainmodule).


HowTo: Building a new LiveCD in two commands
--------------------------------------------
indexterm:HowToLiveCD[HowToLiveCD]
[[BuildingLiveCDtwocommands]]

* <<SettingUptheBuildEnvironment, Setting Up the Build Environment>>
* <<GettingtheTemplatesandmainGraphicsFile, Getting the Templates and main Graphics File>>
* <<IsoMakerExmaple, Two Commands>>
* <<HowDoesItLook, Volia One LiveCD>>

[[SettingUptheBuildEnvironment]]

Setting up the build environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* Add "deb http://www.morphix.org/debian ./" to your /etc/apt/source.list
* apt-get update
* apt-get install morphing-tools

[[GettingtheTemplatesandmainGraphicsFile]]
Getting the Templates and main Graphics File
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* http://svn.sourceforge.net/viewcvs.cgi/morphix/trunk/mmaker/templates/basemod-2.6.9.xml?view=markup[Base Module Tempate]
* http://svn.sourceforge.net/viewcvs.cgi/morphix/trunk/mmaker/templates/morphix-livekiosk.xml?view=markup[MainModule Template]
* MiniModule Templates, http://svn.sourceforge.net/viewcvs.cgi/morphix/trunk/scripts-mini/MorphixMini-KioskSetting.xml?view=markup[1] http://svn.sourceforge.net/viewcvs.cgi/morphix/trunk/scripts-mini/MorphixMini-KioskAddins.xml?view=markup[2]

[NOTE]
.Note on Templates
=====================================================================
These templates may point to a local mirror of the debian repository. Un-comment the remote repository and comment out the local repository.

For example replace the lines

  <!--   <repository type="debian">ftp://ftp.debian.org/debian</repository> --> 
  <repository type="debian">http://127.0.0.1/sid/</repository> 
  
With the lines 

  <repository type="debian">ftp://ftp.debian.org/debian</repository>
  <!--  <repository type="debian">http://127.0.0.1/sid/</repository> -->  
=====================================================================


* http://www.morphix.org/doc/how_tos/images/MorphixLiveKiosk.png[Graphics file used for Rebranding]

.Graphics File used for Rebranding
====================================================================
image:../images/MorphixLiveKiosk.png["Rebranded Boot Splash Background", width=400]
====================================================================

[[IsoMakerExmaple]]

Two Commands
~~~~~~~~~~~~

Run isomaker then morphix-rebrand (The magic two commands)

* isomaker -b ./basemod-2.6.15.xml -m ./morphix-livekiosk.xml -n ./MorphixMini-KioskSetting.xml -n ./MorphixMini-KioskAddins.xml -r http://www.morphix.org/debian -p grub-gfxboot-iso-udeb -p morphix-cdrom-misc-udeb -p morphix-grub-menulist-udeb -p morphix-iso-grubtheme ./morphix-livekiosk.iso
* morphix-rebrand ./morphix-livekiosk.iso ./MorphixLiveKiosk.iso ./MorphixLiveKiosk.png

[[HowDoesItLook]]

Volia One LiveCD
~~~~~~~~~~~~~~~~

Isomaker can take about 45 minutes to run. Morphix-rebrand about 2 minutes.

After this fun you should have a bootable LiveCD

Boot Menu
^^^^^^^^^

image:../images/RebrandBootMenu.png[Rebranded Grub Menu]

Boot-Up Screen
^^^^^^^^^^^^^^

image:../images/RebrandBootSplash.png[Rebranded Boot Splash]

Or if you press F2

image:../images/RebrandBootUp.png[Rebranded Boot Splash Backround]


X-Background / Wallpaper
^^^^^^^^^^^^^^^^^^^^^^^^

Should be the same as the Graphics file.

image:../images/MorphixLiveKiosk.png[Rebranded Boot Splash Backround]



Morphix tools
-------------

A number of commandline tools and scripts are provided in order to help 
you morph. You can find all of these in the Morphix repository, 
see http://www.morphix.org/debian[] for details.


indexterm:module-builder[module-builder]
'- module-builder (morphix-modulebuilder)' + 
        Constructs a module from a directory

indexterm:module-extractor[module-extractor]
'- module-extractor (morphix-moduleextractor)' + 
        Extracts files from a module to a directory

indexterm:make-iso[make-iso]
'- make-iso (morphix-make-iso)' + 
        Creates a bootable ISO from a directory, detects multiple base versions.

indexterm:isomorph[isomorph]
'- isomorph (morphix-isomorph)' + 
        Lists modules on an ISO, adds or removes modules from an ISO, and more!

indexterm:mmaker[mmaker]
'- mmaker (morphix-mmaker)' + 
        Creates a base or main module, using template files. Examples are in /usr/share/mmaker/templates.
See http://www.morphix.org/wiki/index.php/ModuleMaker[]
and documentation in /usr/share/doc/mmaker for details.

indexterm:isomaker[isomaker]
'- isomaker (morphix-mmaker)' + 
        Creates an iso, using one or more mmaker template files.
        See documentation in /usr/share/doc/mmaker for details.

indexterm:make-mini[make-mini]
'- make-mini (morphix-mmaker)' + 
        Commandline tool for building homedir and language minimodules.

'- install2mainmod (morphix-install2mainmod)' + 
        Converts a running hdd install into a mainmodule.

indexterm:minimod-gen[minimodgen]
'- minimod-gen (morphix-minimodgen)' + 
        Provides a commandline interface for building simple minimodules.

'- addtoiso (morphix-addtoiso)' + 
        Add file to an iso, without having to copy the file all within the image

indexterm:morphix-rebrand[morphix-rebrand]
'- morphix-rebrand (morphix-rebrand)' + 
        This script Re-brands a Morphix CD image using a single graphics file.


HowTo: Some Examples to help you start Morphing
-----------------------------------------------
indexterm:MorphingMorphix[MorphingMorphix]
Some 'updated' How Tos to help you get started with Morphing. These HowTos are available on interacive 'How To' LiveCD called 'Morphing-Morphix', much better than a boring document.


A look at MorphingMorphix 0.3
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The purpose of MorphingMorphix is to provide a quick way 
to start Morphing and to showcase all the Morphix tools 
- a LiveCD contruction kit. Just boot the CD and start 
Morphing, no need to install tools, compile applications or
switch operating systems. All that is required is some space
on a connected hard drive. 

You do not have to use MorphingMorphix you just need a debian based system and <<SettingUptheBuildEnvironment, Set Up the Build Environment>>

On MorphingMorphix there are a number of interactive 
HowTo/examples. The examples work best if you work though 
them in order. First configure MorphingMorphix so that some
extra disk space is available. Then work through the 
examples in order. 

Some of the examples, such as using mmaker and isomaker
require access to the internet, so that software can be 
downloaded from repositories to build new parts of a 
MorphixCD. The examples are very machine intensive,
using lots of disk space, memory, and bandwidth.

The following Morphs can be completed from the LiveCD.

* <<Introduction, Introduction to isomorph>>
* <<Remove, Remove Modules>>
* <<MiniMorphExample, MiniMorph Example>>
* <<HomeDir, Saving files in /home/morph>>
* <<AutoBuilding, Mmaker Example>>
* <<MainModule, Chrooting a Main Module>>
* <<Rebrand, Rebrand an ISO>>
* <<BuildingwholeISO, Building a whole ISO from Scratch>>
* <<TestQemu, Testing an iso using Qemu>>

[[Introduction]]

Introduction
~~~~~~~~~~~~

LiveCD are stored as .iso files. Which can then be written 
to a CD. One of the morphing-tools is isomorph. This can be
used to manipulate morphix iso files. 

Isomorph can list, add, del and get files on the Morphix 
LiveCDs.

Isomorph is used in all of the other examples.

For example we will now run the command 

 isomorph --list MyMorph.iso

[[Remove]]

Remove Modules
~~~~~~~~~~~~~~

We have now got our CD Image file, by copying this running 
CD. As you have seen in the last example, this image 
contains the MainModule and lots of MiniModules.  The easy 
way to make a new LiveCD is to build new MiniModules and a 
new MainModule.

Hence the first task is to delete the MainModule and 
MiniModules from the LiveCD image.
Remove Modules

We will again use isomorph

 isomorph --del-all main ./MyMorph.iso ./tmp.iso
 mv ./tmp.iso ./MyMorph.iso
 isomorph --del-all mini ./MyMorph.iso ./tmp.iso
 mv ./tmp.iso ./MyMorph.iso

[[MiniMorphExample]]

MiniMorph Example
~~~~~~~~~~~~~~~~~

The next Morph is making the MiniModule to auto run an 
application once the window manager has loaded.

This Morph is to demonstrate the use of one of the morphix 
tools - morphmini. This is mmaker's little brother. As in 
other examples this makes use of XML template files.

----------------------------------------
<comps>
 <group>
  <minimod>
   <version>0.0.1</version>
   <description>MorphMini launch Morphing-Morphix-GUI</description>
   <minitag>MorphixMini-Launch-MM-GUI</minitag>
   <maintag>ALL</maintag>
   <bootoption>ALL</bootoption>
   <root> <!-- Files or Packages to be overlaid on the rootfile system - good for saving ramspace -->
    <files>
     <local>
      <from>/home/morph/morphix/trunk/morph-scripts/mmorphix/morphing-morphix-gui.sh</from>
      <to>/usr/sbin/morphing-morphix-gui</to>
     </local>
     <local>
      <from>/home/morph/morphix/trunk/morph-scripts/mmorphix/MorphingMorphix.xpm</from>
      <to>/usr/share/morphing-morphix/</to>
      </local>
    </files>
   </root>
   <commandlist> <!-- Commands to be started from minimodule -->
    <X>         <!-- Commands to run in X windows -->
     <command>/usr/sbin/morphing-morphix-gui &amp; </command><!-- &amp; is xml format for & -->
    </X>
   </commandlist>
  </minimod>
 </group>
</comps>
----------------------------------------

We will now build the MiniModule then add the MiniModule to
the the LiveCD.

 morphmini ./MorphixMini-Launch-MM-GUI.xml ./MorphixMini-Launch-MM-GUI.mod        
 isomorph --add mini ./MorphixMini-Launch-MM-GUI.mod ./MyMorph.iso ./tmp.iso
 mv ./tmp.iso ./MyMorph.iso

http://svn.sourceforge.net/viewcvs.cgi/morphix/trunk/scripts-mini/[Other templates for morphmini are available]

[[HomeDir]]

Morphing the Home Directory 
~~~~~~~~~~~~~~~~~~~~~~~~~~~

The next Morph is to save the files in the users home 
directory.

The following will be saved

* Any files and directories in /home/morph
* Hidden system files. (These are the files beginning with a . e.g. .icewm)

The following will not be saved

* The X server setting - these are generated on boot up.

Basically all the files and directories in /home/morph will
be zipped into placed in to a self-extracting MiniModule.

So feel free to save some files, settings, etc within the 
home directory before continuing.This is really useful for 
setting default homepages, menus etc.

The power of a MiniModule is that they are very simple to 
build, but really useful to change the whole impression of 
the cd.

We make the mini-module using one of the morphix-tools
make-mini, along with isomorph to add the MiniModule to the
image file. 

 make-mini --homedir --hidden MorphixMini-MM-Saved-Home.mod
 isomorph --add mini MorphixMini-MM-Saved-Home.mod ./MyMorph.iso ./tmp.iso
 mv ./tmp.iso ./MyMorph.iso

[[AutoBuilding]]

Mmaker Example
~~~~~~~~~~~~~~

MMaker is a tool that is quite simple in nature. Using a 
so-called template, an xml file with all the information 
about the module you want to build, you can auto-build a 
Morphix MainModule. 

That's it kids, we will just have a look at 
morphing-morphix.xml used to build this MainModule 
currently running. 

We will then use mmaker to build a new version of the 
MainModule. Unless you one of the lucky people who has a 
local repository, you will be using the main Debian repository.

You need a fast connection to Debian repository and a lot 
of space to build the MainModule before it is compressed. 

This step could take up to 45 minutes, but hey it is 
automated!

We will use these commands

 mmaker /usr/share/morphing-morphix/morphing-morphix.xml /tmp/morphing-morphix.mod
 isomorph --add main /tmp/morphing-morphix.mod ./MyMorph.iso ./tmp.iso
 mv ./tmp.iso ./MyMorph.iso

As you might have guessed, the template is the key to all of this. A look at one for Morphix LightGUI: [note to editor: the template uses an xml notation, so might not appear when viewing in html]

  <comps>
  <groups>
  <version>0.5</version>
  <id>lightgui</id>
  <name>Morphix LightGUI</name>
  <repositorylist>
  <repository type="debian">ftp://ftp.debian.org/debian</repository>
  <repository type="plain">http://www.morphix.org/debian</repository>
  </repositorylist>
  <description>Morphix LightGUI mainmodule. Includes XFCE4, Firefox,
  Abiword and a host of other goodies</description>
  <type>mainmod</type>
  <suite>sid</suite>
  <packagelist>
  <packagereq>abiword</packagereq>
  <packagereq>xfce4</packagereq>
  <packagereq>mozilla-firefox</packagereq>
  <!-- ... other goodies here ... -->
  </packagelist>
  </groups>
  </comps>

NB This is a partial template see http://svn.sourceforge.net/viewcvs.cgi/morphix/trunk/mmaker/templates/[] for template examples.

Seems simple, doesn't it? The actual template for MorphingMorphix is quite a bit longer (and contains a package to start xfce4 at boot time), but it's very simple to specify which repositories you want to use, what Debian suite you want, what type of Morphix module you want to autobuild and naturally the packages you want. Currently, MMaker can only build base and main modules . A few tags might need some extra explaining:

<repository> - With this tag you define the Debian repository/repositories from which to build your module. Use the type="plain" attribute when you have a repository without separate suites (You can verify this by checking the repository, if it has a Packages file in the root directory of the repository we call it 'plain'). Normal, Debian-style repositories is default

<type> - mainmod, basemod. minimod-type templates are coming up (a separate minimodule generator was constructed before MMaker). It would actually be fairly easy to even have a knoppix-type.

<suite> - sid, sarge, woody (or unstable, testing or stable). These are the three branches of Debian, of which Morphix is derived from.

<arch> - the architecture for which you are building your module. Using an architecture different from the host system isn't recommended and can lead to very interesting errors. It defaults to the architecture of your host system, which should be fine most of the time.

There are a few other tags and commandline options for MMaker, consult the documentation for details.

After your module is built (which takes some time without a local Debian mirror) your uncompressed module will exist in a directory in your /tmp. MMaker will output details of how to recompress it if necessary. We hope MMaker will be useful in letting Morphix work for you!
References
http://www.morphix.org/wiki/index.php/ModuleMaker[Module Maker Wiki page] 

Below is a quick overview on the layout of a template.

--------------------------------------
include::../mmaker/README.template[]
--------------------------------------


[[MainModule]]

Chrooting a Main Module
~~~~~~~~~~~~~~~~~~~~~~~

One of the easiest ways to modify a MainModule is to 
extract the compressed filesystem then change the root 
directory to the extracted file system - chroot.

Once you have issued the chroot command it is just like you
are running the compressed file system, rather than the 
current filesystem.

You can for example

* apt-get install new-applications
* Edit configuration files
* Have fun ....

We will now extract the MainModule. This can take a while 
as ~800M is extracted. We started then dropped in to the
MainModule root. Once we exit we re-compress the MainModule.

We will use the commands

 isomorph --get main ./MyMorph.iso /tmp/
 morphix-chroot /tmp/morphing-morphix.mod 
 isomorph --add main /tmp/morphing-morphix.mod ./MyMorph.iso ./tmp.iso
 mv ./tmp.iso ./MyMorph.iso

[[Rebrand]]

Rebrand an ISO
~~~~~~~~~~~~~~
This script Re-brands a Morphix CD image using a graphic
file. 

The following will be changed

* Grub Titles
* Grub Background
* Username, Hostname
* Boot-up message
* Boot-up background
* Window Manager Wallpaper

Any Graphic file will do. Rebrand.png, Rebrand.jpg or 
Rebrand.gif The  name of the graphics file is important as 
the script takes Rebrand as the new title for the LiveCD.

We will use these commands

 morphix-rebrand ./MyMorph.iso ./tmp.iso Rebrand.jpg
 mv ./tmp.iso ./MyMorph.iso

[[BuildingwholeISO]]

Building a whole ISO from Scratch
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

See <<BuildingLiveCDtwocommands, Building a LiveCD using two commands>>


[[TestQemu]]

Testing an iso using Qemu
~~~~~~~~~~~~~~~~~~~~~~~~~

The next Morph is not really a Morph. It is used to test 
other morphs. It is a common tool for Morphers to use.

Qemu is a generic and open source processor emulator which
achieves a good emulation speed by using dynamic 
translation.

In short: Boot your LiveCD inside your current operating
system. A little slower but faster than burning a cd and 
rebooting. Good for testing.

 qemu -boot d -cdrom ./MyMorph.iso


Appendix FAQ: Frequently Asked Questions FAQ
--------------------------------------------
indexterm:FAQ[Frequently Asked Questions]

* <<AboutMorphix,About Morphix>>
* <<BootingMorphix,Booting Morphix>>
* <<UsingMorphix, Using Morphix>>
* <<InstallingMorphix, Installing Morphix>>


[[AboutMorphix]]

About Morphix
~~~~~~~~~~~~~

What is Morphix ?
^^^^^^^^^^^^^^^^^^^
Morphix is a GNU/Linux operating system on a CD.   

In other words, you don't have to install anything to your harddisk...simply drop in the cd, boot your pc, use Morphix! When you reboot (without the cd in the drive) your machine will be the way you had it before...completely unchanged.


What is Morphix used for ?
^^^^^^^^^^^^^^^^^^^^^^^^^^^
* A whole operating system, to install your programs on and give out. Why send out installation disks, give them a whole operating system with your files.
* A rescue disk. A working operating system to boot your fscked looking hardware.
* A Linux demo CD, spread the word, by showing people a Linux operating system.
* Dust-off old hardware, with defunct harddrives and rejuvenate them.


What is Morphix made out of ?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Morphix is a derivative of Knoppix, another live CD distribution. Both are based heavly on Debian.

Morphix is modular; this means that it consists of a number of parts which together form a working distribution. What does this mean to a normal user? 

Well, that's the good part: he/she doesn't even know about the modules. The modularity is invisible to the user, save the startup-output on the console (which is hidden via a progress-screen in the latest releases). So, if you don't care about how it works, just grab one of the combined isos and boot it!  The best thing is that these isos can be easily modified (Morphed) by you as you require.

Why Morphix? Why should I care?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* Morphix is and will remain Free Software!
* Morphix is a liveCD, with the possibility to install to Harddisk
* Morphix is modular, and can be adapted with less effort
* Morphix is smaller! (only some 190MB for a complete image with icewm, check the mirror)
* Morphix is easily adaptable... and much more!

What's the catch?
^^^^^^^^^^^^^^^^^
Morphix is not finished. It's beta-quality for now! It might not be as uptodate as Knoppix regarding hardware detection, or might handle certain hardware differently

Why Morphix, but not Knoppix ?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You only download what you want. You only download what you need!
o Built-in installer with GUI. PartitionMorpher (a graphical parition program) is under development

* Flexibility. Minimods give you a way to change your environment
* More Software. You can't cram everything in 700MB! 

Where can I get an answer to my questions ?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Try 

. The manual - http://www.morphix.org/doc/how_tos/docbook_html/index.html[] - (which including this FAQ), 
. The wiki - http://www.morphix.org/wiki[]
. The forum - http://www.morphix.org/index.php?option=com_joomlaboard&Itemid=90[]
. The mailing lists 
  * http://lists.sourceforge.net/mailman/listinfo/morphix-announce[]
  * http://lists.sourceforge.net/mailman/listinfo/morphix-user[]
  * http://lists.sourceforge.net/mailman/listinfo/morphix-devel[]
  * http://lists.sourceforge.net/mailman/listinfo/morphix-cvs[]
. irc - We can be found almost daily on the IRC server irc.freenode.net on channel #morphix. See you there!   If your browser supports IRC, (eg Mozilla) this you can use this link, irc://irc.freenode.net/morphix


[[BootingMorphix]]
Booting Morphix
~~~~~~~~~~~~~~~

Morphix Does Not Boot
^^^^^^^^^^^^^^^^^^^^^
First step is to confirm that your computer's BIOS is set to boot from CD 'before' the hard drive(s).

* At this point, shortly after rebooting, you should see a menu listing, Morphix followed by different options. 

The next steps is to test the CD donwloaded correctly and was burnt without any errors. 

* Select from the boot-menu 'Test-cd'. 

If the CD test confirms no errors. The next step is to steer the hardware detection in the right direction, the majority of hardware detection problems (such as blank screen after initial boot) can be overcome using some boot options.

Once you read this boot options section of the FAQ have a look at the list of all possible Boot Options, http://www.morphix.org/wiki/index.php/MorphixBootOptions[]

A dasebase for boot options that other people have used to get hardware working is in the wiki,  http://www.morphix.org/wiki/index.php/MorphixHardwareVsBootOptionsRequired[]

The new grub menu (0.4-1d or later) allows you to select most of the boot options using the menu system and the cursor keys. To add extra boot options to the menu you can edit the command line, just type in the extra boot option. If you do not want to add any further boots option grub menu automatic times out after 5 seconds and starts the boot process.

Blank Screen At End of Boot Process
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Graphic cards are the most problematic to auto-detect. Also to nvidia drivers are not used automatically as only proprietary drivers are available from nvidia.com.

Below are the some most popular boot options used.

* xmodule=vesa
* xmodule=nvidia

Laptop owners may need to use, Use fixed framebuffer graphics.
* fb1024x768 

Try to match the boot code xmodule=GraphicsCard with your Graphics Card

The list of all possible Boot Options, http://www.morphix.org/wiki/index.php/MorphixBootOptions
A dasebase for boot options that other people have used to get hardware working is in the wiki,  http://www.morphix.org/wiki/index.php/MorphixHardwareVsBootOptionsRequired

Hardware Detection
^^^^^^^^^^^^^^^^^^
http://www.morphix.org/wiki/index.php/MorphixBootOptions[Try different boot options]

A database for boot options that other people have used to get hardware working is in the wiki,  [http://www.morphix.org/wiki/index.php/MorphixHardwareVsBootOptionsRequired]


[[UsingMorphix]]
Using Morphix
~~~~~~~~~~~~~

How do I get root, I need to be super user ?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
indexterm:root[Root - Super User]

Open up a terminal and type : -

'sudo su'

To set the root password : -

'sudo passwd'

Why sudo, you might ask? Having a default root pass would provide additional level of complexity. It is also easy to disable sudo if you want to lock down your morph (see /etc/sudoers file).


How do I dial-up, set up PPP ?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Open a terminal shell and type,

* 'sudo pppconfig'
                                                              t               
It asks a few questions like provider, username, password, and phone number that you use to call your ISP. It will also scan for serial devices.
                                                                             
Then use the commands:
                                    
* To connect - 'pon (type the name you gave to the above script for the provider)', eg  'pon pipex'

* To disconnect - 'poff -a'


[[InstallingMorphix]]
Installing Morphix
~~~~~~~~~~~~~~~~~~


[[InstallApt]]
Getting Apt-Get Working - Post Install
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Apt - is an advanced package management tool. With out repeating what already available on the web, a brief read of on of these websites should help

 http://www.google.co.uk/search?q=apt+primer[]
 http://www.google.co.uk/search?q=introduction+to+apt[]

The Morphix liveCD are normally built on a computer with access to a local Debian repository, most 'normal' users will not have a local repository, so we need to change the source list for apt to  look at the central Debian repository.

Open up a terminal windows and become super-user (root)

  su

Run 'nano' a text editor

  nano /etc/apt/sources.list

Before the line beginning; (something like)

  deb ftp://127.0.0.1/debian sid main

Add a #

  #deb ftp://127.0.0.1/debian sid main

Then add

  deb ftp://ftp.debian.org/debian sid main

Then type ('Ctrl-X') to exit and save from nano. Finally do the following command

  apt-get update

Further details:

  http://www.debian.org/doc/manuals/apt-howto/index.en.html[]


Getting Other Packages (Applications) - Post Install
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

First correct read and action the <<InstallApt, Getting Apt-Get Working - Post Install>>. 

In this example we will the morphix-manual.  Most packages and applications are available the debian central repository. so we can skip to <<AptCacheUpdate, apt-cache update>>, but the morphix manual require is found in the Morphix Repository


Become root, confirm that your sources contains the morphix repository.

  su
  nano /etc/apt/sources.list

The file should contain the following line

  deb http://www.morphix.org/debian ./

Then type ('Ctrl-X') to exit and save from nano. 

[[AptCacheUpdate]]
To search for a package, become super-user, update your cache, then search the cache (in this example search for the morphix-manual package).

  su
  apt-get update
  apt-cache search morphix-manual

This return a list of packages matching the search term, in the example morphix-manual

  morphix-manual - Morphix Manual

To install, use the apt-get with the name in the left hand column

  apt-get install morphix-manual

The Morphix-manual, this document is now available locally. Using a browser go to

  file:///usr/share/doc/morphix-manual/html/index.html


What are the system requirements of the different types of morphix? 
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
It is difficult to answer your question specifically, better hardware 
equals better performance. Depending what how you are planning to use 
Morphix.

I have Morphix running on the following machines, with the following 
installs

. Morphix Gnome 
  * Pentium III 500 MHz - 256M Ram - Runs ok.
  * Pentium 4 2.4GHz - 1 G Ram - Runs fast
. Morphix Light
  * VIA Eden 600 MHz - 512M Ram - Runs fast.
  * Pentium 1  75MHz - 70M Ram - Runs a little slow
. Morphix Derivative, Photo-ix, LiveKiosk, hacked for low memory
  * Pentium 1  75MHz - 16M Ram - Runs slow


Other FAQs to follow.


Appendix Transition
-------------------
This second documents the transitional changes version to version of Morphix, especially bases.

It reflects the README.transition on the CDROM.


Transition to unionfs-wielding base (0.5-pre5)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Since Morphix 0.5-pre5 unionfs is used instead of cowloop.

Unionfs doesn't require a specific filesystem. You can still use the
cowloop-way with module-builder -t ext3, or you can use the default (iso9660).
Both should work.


Transition to non-floppy emulation base
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The files in /base/boot.img (the floppy image) are now available in /boot
ISO-construction now happens using the following command:

  find $SRC/ -type f -print0 | xargs -0 md5sum > $SRC/md5sums.txt
  mkisofs -pad -l -r -J -v -V "Morphix LiveCD" -b boot/grub/iso9660_stage1_5 -c base/boot.cat -no-emul-boot -boot-load-size 4 -boot-info-table -hide -rr -moved -o $DEST $SRC


Transition to >=2.6.x-wielding base
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use the tips below, however be aware that you need cloop-utils version 2.0 or 
higher. You may also use squashfs and zisofs-compressed modules, if you prefer
these, however the base module itself (/base/morphix) should be compressed
using cloop.


Morphix Readme on <0.4-0c transition to >=0.4-1
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

What are the main changes?

* new cloop version, incompatible with old version
* different loadmod.sh needed for mainmodules
* /cdrom, /cdrom1 and /floppy need to be directories
* autofs disabled

Make sure you have the (old) mainmodule unpacked in a directory (you can get the old extract_compressed_fs from http://am.xs4all.nl/morphix/scripts to accomplish this). 
Get the latest cloop-utils from Debian sid or Morphix 0.4-1 (or grab them from http://developer.linuxtag.net/knoppix/). 
Then, build the module like usual. If you want there is a module-builder script up on http://am.xs4all.nl/morphix/scripts/module-builder2.pl

You can get the new loadmod.sh from http://am.xs4all.nl/morphix/loadmod-0.4-1.sh or from /morphix/loadmod.sh in a 0.4-1 mainmodule. Copy it over the old loadmod.sh.

rm /cdrom, rm /floppy and mkdir /cdrom, mkdir /cdrom1, mkdir /floppy

uncomment anything in your /morphix/init.sh regarding autofs. Use the /morphix/init.sh of 0.4-1 mainmodules as a guide if you are unsure.

Appendix Man Pages
------------------
http://www.morphix.org/doc/how_tos/all_man_pages/html/index.html[The man pages are availble as a seperate document]

Appendix Legal Issues
---------------------

0.5-releases of Morphix Base are fully open source under the DFSG. Some Base ISO's do contain the nvidia minimodule, in /minimod, but this is easy to remove. Likewise, Morphix LightGUI 0.5-pre4 is also fully open source.


Other issues?
~~~~~~~~~~~~~
There are however some packages for which licensing isn't fully clear. The most prominent package is the mplayer mediaplayer (http://www.mplayerhq.hu/homepage/), the project claims that it is GPL, but it isn't in Debian yet for legal reasons. However, it is distributed by other distributions.

Morphix' code
~~~~~~~~~~~~~
As for any Morphix-specific software: all is licensed under the GPL. All screenshots, wallpapers and other graphics in Morphix can be freely used. If you want to modify them, you may, but with both the software and graphics I expect that credit is given where credit is due and for software you must follow the GPL license supplied. Morphix is an unofficial Debian-derivative, but I'd appreciate it if you give them credit for their great distribution, as without it Morphix wouldn't be possible. Also, mention Knoppix, as it was it that started the Morphix project.

Bottom-line
~~~~~~~~~~~
Anyway, the choice is yours to take. I am not a lawyer, but I strive to know about everything that goes into morphix. I can however not be 100% sure if everything can be exported to every country. If in doubt, checking with your attorney is always the best thing to do. Morphix is a growing community that started as a private project and if you find new information or violating software just let us know and it will be dealt with. I'm pretty confident about it, but we're human, not a company and can't idemnify users or developers. Yes, we're human.



Appendix About: This Document
-----------------------------
*All text on this manual is available under the terms of the GNU Free Documentation License*

Compiled by Brendan M. Sleight, aka bmsleight. Using documents from many sources and help from many people. The 'source' file to generate this manual in in the morphix cvs '/how_tos/morphix_docbook.txt' 

Thanks to Thanks to http://aquariusoft.org/page/linux/livecd_howto/[aquatix] for the Fast introductions.

This document cvs reference is :

$Id: morphix_docbook.txt 2423 2006-09-29 21:46:44Z bmsleight $

Feel free to edit it, post patches or diffs. 

Writing in XML is not easy for mortals like myself, but I wanted to use a docbook as it's the 'correct format'. To get around this problem, I have used a text file and 'asciidoc' to generate the xml and then the html. Their is a simple script containing the commands used for conversion.
 
 /cvsroot/morphix/how_tos/docbook_html/prepare_html.sh

The xmlto html occasionally may fail if your syntax is wrong in text file, but this is quite rare. Alas no one can avoid death and (syn)taxes.

See http://www.methods.co.nz/asciidoc/[] for information on the wonderful application asciidoc.

Bibliography
------------

+ [[[taoup]]] Eric Steven Raymond. 'The Art of Unix Programming'.
  Addison-Wesley. ISBN 0-13-142901-9.

+ [[[walsh-muellner]]] Norman Walsh & Leonard Muellner.
  'DocBook - The Definative Guide'. O'Reilly & Associates. 199.
  ISBN 1-56592-580-7.

+ [[[oreilly]]] Kyle Rankin. 
  'Knoppix Hacks 100 Industrial-Strength Tips and Tools'
  ISBN: 0-596-00787-6

Glossary
--------
Glossaries are optional. Glossaries are an example of an AsciiDoc
VariableList, the AsciiDoc glossary entry terms are terminated
by the `:-` characters.

Grub:-
        GNU GRUB is a Multiboot boot loader. It was derived from GRUB, GRand Unified Bootloader, which was originally designed and implemented by Erich Stefan Boleyn.

A glossary term:-
        The corresponding (indented) definition.

A second glossary term:-
        The corresponding (indented) definition.


Index
-----

////////////////////////////////////////////////////////////////
The index is normally left completely empty, it's contents being
generated automatically by the DocBook toolchain.
////////////////////////////////////////////////////////////////