[Lunar-commits] r15618 - lunar-doc/trunk/lunar-manual
ca3sar
ca3sar at lunar-linux.org
Thu Jul 7 00:57:06 UTC 2005
Author: ca3sar
Date: 2005-07-07 00:56:56 +0000 (Thu, 07 Jul 2005)
New Revision: 15618
Added:
lunar-doc/trunk/lunar-manual/1installation.tex
lunar-doc/trunk/lunar-manual/2using_lunar.tex
lunar-doc/trunk/lunar-manual/3troubleshooting.tex
lunar-doc/trunk/lunar-manual/4inside_lunar.tex
lunar-doc/trunk/lunar-manual/5getting_to_work.tex
lunar-doc/trunk/lunar-manual/6development.tex
Modified:
lunar-doc/trunk/lunar-manual/Lunar_Book.tex
Log:
changed names of section files. as discussed with hardkrash, introduced listings package for code. fixed compile errors
Added: lunar-doc/trunk/lunar-manual/1installation.tex
===================================================================
--- lunar-doc/trunk/lunar-manual/1installation.tex 2005-07-06 17:27:25 UTC (rev 15617)
+++ lunar-doc/trunk/lunar-manual/1installation.tex 2005-07-07 00:56:56 UTC (rev 15618)
@@ -0,0 +1,332 @@
+\chapter{Installation of Lunar Linux}
+\includegraphics[scale=0.2]{./image/logo.pdf}
+ is a linux distribution in that it is not binary based, as are most distributions, but is instead built entirely by compiling sourcecode, using your own custom optimizations. Essentially, it installs a complete bootstrap development system on your machine, and then you tell the Lunar package manager what tools you want, and it builds the entire system by downloading current source code and locally compiling an optimized system tailored toward your specific needs.\par
+
+The result is a leaner, meaner, refreshingly uncluttered, and strikingly faster operating system than most linux distributions.\par
+
+
+
+This Chapter of the book is meant to guide you through the installation process as painlessly as possible. It assumes that you have some experience with linux or another Unix variant, and have a general idea of what you are doing. If you are unfamiliar with such things as partitions, or have never used linux before, Lunar may not be the best introduction for you into the world of open source.
+Take a look at Chapter \ref{comty} to see, how you can contact the community for help.
+
+With that said, we hope you enjoy using Lunar!\par
+
+
+\section{Getting the ISO}
+
+The primary site for retrieving the ISO is \textit{ lunar-linux.org }. There, under \textit{Downloads} you will find links to our US, EU, and Internet2 mirrors, as well as a Bittorrent link. As of this writing, the current version of the Lunar ISO is version 1.5.0.\par
+
+Locate and retrieve the file lunar-1.5.0.iso.bz2. After downloading this file, you will need to unpack the ISO using bzip2. Windows users may need a program like WinZip. Mac should unzip the file by itself. Then all that is left to do is use your favorite program to burn the ISO to a cdrom and begin the installation. \par
+
+It should be noted that this ISO and Lunar use devfs for device management. \par
+
+We are assuming the you are installing Lunar as your primary OS. Make sure you have a backup of any important data that you need to retain. The Lunar Linux Project and its developers are not responsible in any way for any loss of data on your system!\par
+For installation parallel to an other OS like Micro\$oft Windows, install it first, but leave unpatitioned space for Lunar. Refer to the bootloader section \ref{bootl} in this chapter to see, how you can integrate it to your boot menu. This way Windows will be installed on the first partition of your disk. If you install on different disks things get more complicated. You need to install the bootloader on the first disk, from which your box boots. Ask the community if you need help: Chapter \ref{comty} \par
+
+
+\section{Booting the ISO}
+
+\begin{figure}
+\begin{center}
+\includegraphics[width=0.8\textwidth]{./image/install1.pdf}
+\end{center}
+\caption{Boot Menu}
+\end{figure}
+
+Upon booting the ISO, the first thing you will see are options for booting the ISO kernel, or for performing RAM tests. For people who need to load extra modules for example for IDE or SCSI devices. There is even a safe mode which will disable DMA, MTRR, RAID, LVM, USB keyboards, NTFS, HPFS, Advanced Partitions, and Firewire. For more extensive help on each point you can press \textit{ F1} to \textit{F4}.
+
+Most folks, however, will be just fine pressing enter at the boot prompt and loading the default kernel. The kernel will ask you for other resolutions to display the console in. Again you will run savely with just pressing \textit{space } \par
+
+\begin{figure}
+\begin{center}
+\includegraphics[width=0.8\textwidth]{./image/install2.pdf}
+\end{center}
+\caption{Welcome to the Lunar Linux Installer}
+\end{figure}
+
+After loading the kernel, you will be presented the Lunar Linux installer. It will guide you through the rest of the setup process. By pressing \textit{ I} or \textit{enter} you may read a short Introduction. The installer goes through 14 steps which can be navigated forward and backward by pressing the \textit{up} and \textit{down} button and \textit{enter}. You can navigate to the settings by pressing the \textit{left} and \textit{ right} arrow keys. Here one can shell out at any time of the installation process, as well as load more kernel modules and toggle the behaviour of the guided menu. \par
+
+To come to the next step press \textit{down} and \textit{enter} at the first screen.
+
+\section{Customization Settings}
+
+We now have some customization settings to configure. You can choose keyboard map, console font and global language. \par
+
+\begin{figure}[h]
+\begin{center}
+\includegraphics[width=0.8\textwidth]{./image/install3.pdf}
+\end{center}
+\caption{Localise your Lunar Linux}
+\end{figure}
+
+When u made a selection the menu point will change its color to green. In the keyboard map choose the one apropriate for you. Most americans will need \textit{us} while germans may need \textit{de} and danish people \textit{dk}. The language setting should explain itself ;) %console font ?? wtf should one choose ? this is really cryptic for me.
+
+You will also need to choose an editor, as you are going to need one later on in the installation for setting up your lilo or grub configuration. The six choices available are vi, joe, nano, e3, emacs and zile. If you have never used a text editor in linux before, nano is the best choice for you. If you skip the Native Language Support option, the system will install the default editor, nano for you. Now press \textit{F} to get one step forward. \par
+
+\section{Setting Up Partitions}
+
+\begin{figure}[hb]
+\begin{center}
+\includegraphics[width=0.8\textwidth]{./image/install4.pdf}
+\end{center}
+\caption{Partition Setup}
+\end{figure}
+
+The next step is to set up partitions on your hard drive. Upon selecting the "Partition Drive" option, you will be shown a list of all the discs the kernel has detected. If we assume that you have one hard drive connected via an IDE channel, which will show up in the menu as "disc0". After selecting the disc to partition, you are given the option of using one of three partitioning programs. They are:
+
+\begin{itemize}
+\item cfdisk -- A menu driven partitioner, and very easy to use. If you are unfamiliar with various partitioning programs, this is the best option for you.
+\item fdisk -- Text based partitioner that requires a little more know-how than cfdisk. More experienced users will probably use this program. However new users should not be daunted, as it does have help offered at every step. You can leave by pressing \textit{q }and \textit{enter}
+\item parted -- Text based partitioner that is good for advanced users. Parted is excellent for resizing current partitions on your hard disk, however be forewarned that resizing partitions is an excellent way to hose your entire disc.
+\end{itemize}
+
+For our example, we have one 40GB IDE drive and we'll set up six partitions; /, /boot, /home, /usr, /var, and a swap partition. It's a good idea to keep certain directories, such as /var and /usr on separate partitions, as this can save you a lot of headache in the future incase your disk ever completely fails on you and you need to recover data (god forbid!). Also, when you have a separate /boot partition as we have in our example, you need to have your partitioning program mark that partion as active or bootable. In our example, if we were using fdisk, you would press "a" at the command line, and then select part1 as the active partition.\par
+
+If you are installing on a machine together with an other OS you perform these steps in the unpartitioned space and leave the other partitions untouched. For installation on different disks just choose the other disk (disc1 ... ) \par
+
+You might also want to install a /tmp partition. By default, Lunar will create a tempfs filesystem mounted on /tmp (tempfs minimizes filesystem fragmentation because it resides in volatile memory). This can be a good choice if you have a lot of memory on your machine. If memory is tight, we recommend creating a /tmp partition to minimize filesystem fragmentation.\par
+
+It is important to note that you can not mount the directories /etc, /bin, /sbin, /dev, /lib and /proc on separate partitions. These directories need to be contained within the root ("/") directory. The installation program should block you from doing this, but it's best not to try.\par
+
+Here's our partition setup:\par
+
+\begin{enumerate}
+\item /boot 100MB
+\item / 4GB
+\item swap 1GB
+\item /usr 10GB
+\item /var 10GB
+\item /home 15GB
+\end{enumerate}
+
+In order for you to have more than four partitions on a single drive, the fourth partition is made into what is known as an extended or logical partition in which the fifth, sixth, and seventh (etc, etc) partitions reside. For our example above, if we were using fdisk, we would make the fourth partition an extended/logical partition that was 35GB, and then the fifth, sixth, and seventh partitions in our scheme resided within it. However, if we used cfdisk, we would just worry about creating six partitions, making sure that the first three are the primary type, and the last three logical.\par
+
+Note that the names and mount points for these partitions will be assigned during the next step of this process, when you mount the partitions. Write down exactly what partitions you are planning to create because it can otherwise get confusing!\par
+
+Lunar offers two choices when it comes to swap. You can set up a swap partition, as we have in our example, or you can set up a swapfile in the root directory. We recommend setting up a swap partition, as you will get better performance with it than with the swapfile. However, there may be a need for you to set up the swapfile instead, which can be setup and activated after you have mounted your other partitions.\par
+
+
+\section{Mounting Partitions and Creating Filesystems}
+
+\begin{figure}
+\begin{center}
+\includegraphics[width=0.8\textwidth]{./image/install5.pdf}
+\end{center}
+\caption{Creating one swap, one / and one /usr partition}
+\end{figure}
+
+After setting up your partitions, you need to mount them and create file systems. Select the menu option "Select Target Partitions" and verify that you are indeed done creating partitions.\par
+
+The installer will warn you at this point that the root partition (as in "/", not "/root") needs to be mounted first. Select the disc that the root partition should be on. In our example, we are going to use disc0. Our root partition is going to be on disc0/part2 then we select which filesystem we would like to use.\par
+
+\begin{itemize}
+ \item ext2 (Second Extended File System) -- Version 2 of the Extended File System, which was designed for linux as a replacement for the Minix Filesystem. Ext2 is not a journaled filesystem, which means that you'll need to perform disc recovery operations after a power failure or other such system crash. This filesystem is available with all kernels on the ISO.
+ \item ext3 (Third Extended File System) -- Version 3 of the Extended File System, which is essentially just the journaled version of ext2. This filesystem is available with all kernels on the ISO.
+ \item reiserfs (Reiser Filesystem) -- Journaled filesystem created by Hans Reiser that is excellent for use with extremely small files. This filesystem is available with all kernels on the ISO.
+ \item jfs (Journaled File System) -- Created by IBM for AIX, IBM's brand of Unix, and later ported to linux by IBM under the GPL. A journaled filesystem that is very good at handling high throughput issues. This filesystem is available with all kernels on the ISO.
+ \item xfs -- Created by SGI for IRIX, SGI's brand of Unix, and later ported to linux under the GPL. A journaled filesystem that SGI claims is better than any other at handling extremely large files and sparse files. This filesystem is only available with the lunar or grsec patched kernels, which we will come to in a few steps.
+\end{itemize}
+
+We recomment to use ext3 as your filesystem.\par
+After selecting the filesystem type you wish to use, you will be prompted through a series of steps to initialize the partition. You'll notice that the prompts are quite redundant in nature in order to be absolutely positive that you will not inadvertantly erase crucial data that you might have on a working filesystem. In addition, if you have more than four partitions, as we do in our example, you don't want to mount any file systems on the fourth partition, as it is the extended partition that houses the fifth, sixth (and so on) partitions.\par
+
+As we mentioned earlier, there is an option in the installation process to set up a swap file in the root partition instead of a swap partition as we have done in our example. The next option after mounting your filesystems is to set up the swap file if you so desire. If you have set up a swap partition already, as we have done, you can skip this step. Otherwise, you can set up your swap file here, and the only thing you need to tell the installer is how large you want the file to be.\par
+
+\section{Transferring Lunar To Your Partitions}
+
+\begin{figure}
+\begin{center}
+\includegraphics[width=0.8\textwidth]{./image/install6.pdf}
+\end{center}
+\caption{Transfering Lunar Linux}
+\end{figure}
+
+Next, we need to transfer the core Lunar system to the partitions that you now have created. Select "Install Lunar", and the system will proceed to tansfer all of the neccessary files for you. Be forewarned that the /usr transfer can take some time, espescially on older or slower systems, so don't panic and think that your system has frozen. It's just doing its thing.\par
+
+
+
+\section{Setting Up Your GCC Architecture Optimizations}
+
+\begin{figure}
+\begin{center}
+\includegraphics[width=0.8\textwidth]{./image/install7.pdf}
+\end{center}
+\caption{Optimisations and Bootloader}
+\end{figure}
+
+We reached step 7 of 14, thats the half, so lets go on ...
+The architecture optimizations is a crucial step, since what you choose will make your system fly! However, it is important that you do not overdo it on you optimization settings, as certain selections can, in some instances, break code while compiling.\par
+
+The first option wants to prevent you from overdoing the optimisations. It will hide all compiler flags that are known to cause big trougle. So if you leave it enabled your save.
+
+Now choose your preferred compiler. The default choice here is GCC 3.x, and is the preferred choice as GCC 2.x is no longer under development, and GCC 3.x is known to make compiled code run faster. For our example, we are going to use GCC 3.x.\par
+
+Next we have the platform selection. This question would seem to be rather silly, since our ISO only boots up on x86 systems, but we like to plan for the future. You'll want to say x86 here.\par
+
+Now we move onto the basic optimizations . As you can see, the options speak for themselves. Your choice depends on what your needs are. Most folks will want to use -O2 / faster here, as it is the wisest choice. More advanced users may want to use the -O3 / fastest option, but it's not for everyone. If you're short on disk space, you would take the -Os / Small option. \footnote{As an example, we used -Os for the ISO since we were working within a confined amount of disc space.} Those of you with older or slower systems that wouldn't be able to take advantage of faster optimizations may choose a more conservative setting like -O1 / fast . For our example system, we will choose -O2.\par
+
+After choosing your basic optimization level, you'll need to tell the compiler what type of processor you have. This may seem unimportant, however the GCC 3.x compiler has ways of optimizing code for certain processors, even though they all may be x86 based. For example, GCC 3.x has certain optimizations it can perform on code for Pentium 4 machines, but not for Pentium 3. Our example machine is a Pentium 3, so we are going to select that.\par
+
+We could also select i686, as a Pentium 3 falls within that architecture. Choosing i686 is a more conservative choice than Pentium 3, as GCC 3.x will not try certain optimizations with a more general choice like i686.\par
+
+Next are options for the C and C++ compiler, called -pipe. Very few people, if any, would need to turn off the -pipe option, so in our example we are going to leave them checked.\par
+
+Following that is the screen for linker options, where you will find that "-s Strip" has already been checked off. Very few people will want to uncheck this option, so we will leave this screen as is. After that, we have some addons for compiler caching and distributed compiler support. Most folks will not need either one of these\par
+
+
+\subsection{Adding Additional GCC Optimizations}
+
+
+\begin{figure}
+\begin{center}
+\includegraphics[width=0.8\textwidth]{./image/install8.pdf}
+\end{center}
+\caption{Kernel Build Menu}
+\end{figure}
+
+Here we state the more riskier optimisations. If you are new to whole thing and dont know \textbf{exactly} what you doing leave them as they are. There are too many to go into much detail here, but suffice to say that you should choose carefully. As we mentioned in the prior section, certain optimizations will cause compilation errors or even failures. An optimization such as "-ffast-math" is very risky because it breaks certain rules to get faster code, and would only be used by the bravest of souls looking to endure lots of pain. More information about GCC 3.x optimization strings can be found on the gnu.org website. \par
+
+Some options involves setting up the number of concurrent makes and stack parameters. As the hint mentions on the "Concurrent Makes" screen, you'll want to enter in the number of cpu's your machine has. Unless you have a machine with more than one processor, you'll want to leave this field blank. The stack parameters is also fairly straightforward. The warning on that screen says that this field is best left empty, and so that is exactly what we will do with our example. \par
+
+We are now finished setting up our GCC optimizations! When you have you lunar system up and running, you can always change and tweak these GCC settings by typing "lunar" at the commandline prompt, and going to "Optimization Settings". In addition, if you aren't that familiar with what your processor is capable of using for optimizations, you can go to the shell out option on the ISO and type
+
+
+\begin{flushleft}
+\textit{ cat /proc/cpuinfo}
+\end{flushleft}
+
+
+at the prompt and the system will show you all the optimizations that the processor reports it can handle.\par
+Now we can install the bootloader Package. Lunar offers you three choices: Lilo, Grub and None. Most people would want to choose Lilo, as it is easy to install, the configuration will take place after the kernel installation.
+
+\section{Building Your Customized Linux Kernel}
+
+\begin{figure}
+\begin{center}
+\includegraphics[width=0.8\textwidth]{./image/install9.pdf}
+\end{center}
+\caption{Kernel Build Menu}
+\end{figure}
+
+We have now come to the most important part of the installation; the configuration of the kernel. The kernel is the heart of linux, and without it, nothing would work. Configuration is, actually, a rather simple process. All you need to remember is to not panic, and that lunar is going to do most of the work for you. Here are a few pointers that will make the configuration a breeze for you.\par
+
+\begin{itemize}
+\item Help is a click away! The people working on creating and maintaining the linux kernel have help placed throughout the entire configuration process. If you're not sure what something does, just look at the help file for whatever item you're on, and it will almost certainly explain what it is and what it does. The most handy thing is that every help file will suggest whether you should really use the item or not. Many help files end with "If you're not sure, it is safe to say N here", thus letting you know that it is safe to leave that particular item out of the kernel.
+\item You can use a precompiled kernel! The configuration used to make the kernel for the ISO is the same configuration you'll see when you start your kernel customization. If you leave the configuration the way it is, the only thing you truly have to worry about is your network and, if you want it, sound. There are also six default configurations available on the ISO that are available to you. You can load these by choosing precompiled kernel in the screen above. Its recommended to choose 2.4.20-normal.
+\item Never build filesystems or core components as modules! Make sure that whatever filesystems you decided to use for your partitions earlier are built into the kernel, and are not separate modules. Likewise, make sure that certain crucial things like ide and scsi drivers are not modules, as this will make your machine unbootable. (This rule doesn't apply to the scsi low level drivers though; they can be modules.) Modules are kernel drivers that can be manually activated and deactivated after the system has been booted, but not during boot time. The kernel from the ISO already has all the filesystems available during the installation built into the kernel, so if you don't change anything there, you will be fine.
+\end{itemize}
+
+There are serveral kernels for you to choose from. They are:
+%someone take a close look at these specs !!
+\begin{itemize}
+\item Linux 2.4 -- The default kernel for Lunar which is the Linus tree with some handy patches for the xfs filesystem, firewire, ext3, and several other fixes.
+\item Linux-2.4-stable -- The Linux kernel with only crucial fixes.
+\item Linux-2.4-vanilla -- This is the Linus tree with only critical patches for certain drivers that were created after the 2.4.29 kernel was released.
+\item Linux-2.4-grsec -- This is almost the same as Linux 2.4, but with grsecurity, cpu frequency scaling, gcc 3.x architecture types, and crypto support.
+\item Linux-2.4-agr -- The aggressive patch includes everything from the standard patchset as well as the low latency, pre-emptive, and gcc 3.x architecture type patches.
+\item Linux-2.4-om --A Kernel for OpenMosix clustering %gimme more info
+\end{itemize}
+
+For our example, we are going to use linux with the aggressive patchset (Linux-2.4-agr). \par
+
+The final question before you begin is which type of configuration method you would like to use.\par
+
+\begin{itemize}
+\item config -- The original way to configure the linux kernel. It is completely text based, and assumes you know what everything is. Unless you've been using linux since its inception, you probably don't want to use this method.
+\item menuconfig -- As the name implies, a menu driven version of the kernel configuration. This is the easiest, and by far the most popular way of configurating your kernel.
+\item xconfig -- If you have an X server running, you can use this option to configure your kernel using a nifty GUI interface. You won't be able to use this on the ISO, but once your system is up and running with X, you can use this option. If you do choose this option while installing from the ISO, the system will fall back to next available configuration method, in this case menuconfig, so there is no harm in selecting it if you do.
+\end{itemize}
+
+For our example, we are going to use menuconfig. Once Lunar is finished applying the patches for the kernel, which can take a minute or two, you'll be brought to the configuration screen for the linux kernel. Once you have completed configuring your kernel, you'll get one more prompt from the installer asking if you want to go back to the configuration in case you exited by mistake or forgot something. If everything is good to go, say no here and sit back for a few minutes while your kernel compiles.\par
+
+
+
+
+\section{Configuring Your Bootloader} \label{bootl}
+
+\subsection{Lilo}
+
+If you chose to use lilo and also said yes to automatically configuring and running lilo, then most of the work is done for you. If you chose not to hand edit lilo.conf, however, be warned that the default configuration has the system set up to be password protected on boot. You can change this by selecting the option from the menu "Reconfigure LILO".\par
+
+To turn off password protection, you will need to comment out (with the symbol "\#") or delete two lines in your lilo.conf file. The first is \lstinline!password=lunar!, which is found in the top section of the file, and the other is \lstinline!restricted! which is found right below the name of your kernel in the second section.\par
+
+The other item of note is whether you want lilo to reside in your MBR (Master Boot Record) or on the first sector of your /boot partition. The line in your \textit{lilo.conf} file to edit for this purpose is\par
+
+\begin{lstlisting}
+boot=/dev/discs/disc0/part1
+\end{lstlisting}
+
+To make lilo get installed on the first sector of your /boot partition, you would leave this line as it is. If you want lilo to be written to your MBR, which is the recommended method, you would change the line to read
+
+\begin{lstlisting}
+boot=/dev/discs/disc0/disc
+ \end{lstlisting}
+
+Of course, these examples are pertinent to our setup that we have been using thoughout this manual. Your actual lilo.conf file may be different.\par
+
+\paragraph{Integrating an other OS}
+
+If you have an other operating system installed on a harddisk, you can configure lilo like this:
+
+\begin{lstlisting}
+other = /dev/hda1
+label = Windows
+\end{lstlisting}
+
+as you see in this configuration Windows is installed on /dev/hda1, which is the first partition on your hdd. It will appear as "Windows" in the boot menu. \par
+\textbf{Note} The partition needs to be marked as "bootable".
+
+\subsection{Grub}
+
+%there is something from nestu in svn about this... put it in here pal !
+If you chose grub as your bootloader, you will need to set up the configuration file entirely on your own. An example would be: \\
+
+\begin{lstlisting}
+default 0
+timeout 30
+color white/blue white/black
+title linux-2.4.20
+root (hd0,0)
+kernel /vmlinubz-2.4.25-r5.0.0 root=/dev/hda2 devfs=nomount
+ \end{lstlisting}
+
+
+As we mentioned earlier in the partitioning section, you would want to mark your /boot partition as active. With grub it is imperative that you mark your /boot partition as active, otherwise grub will not work at all when you are finished with the installation and reboot to your new system.\par
+
+
+\section{Installing The MBR}
+
+If you installed lilo or grub into the MBR then you don't need to use this step. If, however, you chose to place lilo or grub in the first sector of the /boot partition, then you would use this option. The MBR install is especially useful if the hard drive you are installing Lunar on is brand new and has never been used.\par
+
+
+\section{Setting the root passwort}
+
+\begin{figure}
+\begin{center}
+\includegraphics[width=0.8\textwidth]{./image/install10.pdf}
+\end{center}
+\caption{Setting the root password}
+\end{figure}
+
+After the kernel is finished you will end up at the kernel choosing screen. You need to choose exit and can now set the passwort for the root account. Choose a good password, like G49dN448e . A not so good password would be your name, your birthday or some other word that actually makes sense.\par
+
+\textbf{Note:} Never choose this account as your default user. This would be a great security risk, as root can do everything with your system. \textbf{Always} use an other user that is even not in the root group and has no other privileged rights. Other popular OS are in to deep trouble because of an other default setting in this place ... \par
+
+\section{Setting Up Networking, Services and other bits}
+
+\begin{figure}
+\begin{center}
+\includegraphics[width=0.8\textwidth]{./image/install11.pdf}
+\end{center}
+\caption{Setting up networking, services, ssh keys and timezone}
+\end{figure}
+
+The final steps are to set up networking. Select the \textit{Set Up Networking} option, you can configure a series of settings, as to what kind of card you have (only needed if you built your networking device as a module, and not part of the kernel), if you need to set up wireless or not, and whether you'll need to use dhcp or not. You should be familiar enough with your network to set this up on your own, as the questions put to you are very straightforward. You can setup DNS configuration, host and domain name and the global gateway. All this things can be changed later by running the \textit{lnet} utility. See \ref{lnet} .\par
+Further you can setup the services that are started automatically at bootime. This can be changed later by the lservices tool. See Chapter \ref{lserv} \par
+We are nearly finished, at last you need to set up your timezone. This should be pretty straightforward for just about everyone. Go to \textit{Select Timezone} and you will be presented with a long list of countries and some of the more popular timezones. The only thing to note is to be sure of whether your hardware clock is set to local time or to UTC. Most everyone will choose local at this stage.\par
+
+\section{Reboot!}
+
+Once you have completed setting up your networking, you are finished installing Lunar Linux! Congratulations! Select the option \textit{Done} and remove the cd from the drive when it ejects. Your Lunar system is now ready to go!\par
+
+\textbf{Have Fun!!}
\ No newline at end of file
Added: lunar-doc/trunk/lunar-manual/2using_lunar.tex
===================================================================
--- lunar-doc/trunk/lunar-manual/2using_lunar.tex 2005-07-06 17:27:25 UTC (rev 15617)
+++ lunar-doc/trunk/lunar-manual/2using_lunar.tex 2005-07-07 00:56:56 UTC (rev 15618)
@@ -0,0 +1,187 @@
+\chapter{Using Lunar Linux}
+%everything that comes after first install.
+
+\section{First Steps}
+%update of lunar and moonbase etc
+
+After the successful installation the whole world of Lunar Linux awaits you. You will see the advice to read man \lstinline{lfirsttime}, which will give a good introduction to the handling of Lunar. In many points its quite redundant to whats presented in this chapter. Further you are reminded of the tools the developers wrote for you, to make configuration easier. For example \lstinline{lnet} and \lstinline{lservices}. See chapter \ref{tlhelp} for more details about them.
+
+\subsection{Setting up and testing the network}
+
+ This step is crucial to your future success with Lunar Linux. If you haven't set up your network card yet try it with \lstinline{ lnet}. Remember, you need to know about your current network card's driver and have the kernel built the appropriate modules for it.
+
+\subsubsection{Check your network settings}
+
+Once you've set up your network card correctly, try to ping out.
+
+\begin{lstlisting}
+ping google.com
+\end{lstlisting}
+
+ If it doesn't work you may be having a name resolution problem, try pinging to the IP address instead of the name.
+
+\begin{lstlisting}
+ ping 216.239.57.99
+\end{lstlisting}
+
+ If pinging to IP is working but pinging to name fails, check the /etc/resolv.conf file and see if the nameserver entries are there. You may also want to check the man page, \lstinline{man resolv.conf} if you are not familiar with the entries which should be in that file.
+
+\subsubsection{Check the network device}
+
+ If pinging the IP address fails, check to see if your network interface is up and running. You may use the command \lstinline{ifconfig} to see the interface's status. You must be able to see the details of your network interface in the output of ifconfig. If you cannot, then check if your NIC (network interface card) module is loaded (assuming you are using a modular kernel); use the command \lstinline{lsmod} to see the already loaded modules and see wether the module for your network card is already loaded. If you do not know for sure what type of network card you have try executing the command: \lstinline{cat /proc/pci | grep} Ethernet or \lstinline{ lspci}. This should give the manufacturer and model name of your ethernet card. \par
+
+If your NIC module is there but your interface is not up, reconfigure the interface with lnet and test again. If your NIC module is still not listed in the output of lsmod, the chances are you have misconfigured the kernel or misconfigured your network. To check the kernel modules, try
+
+\begin{lstlisting}
+ ls -l /lib/modules/`uname -r`/kernel/drivers/net
+\end{lstlisting}
+
+to see the network modules available with the current kernel. If the your NIC's kernel module doesn't show up you probably have to reconfigure and recompile your current kernel to include the appropriate module(s). \par
+
+\subsubsection{lnet or manual configuration}
+
+Your network setting can be configured completely using \lstinline{lnet}; just make sure you set up your interface correctly as needed. If you encouter problems after having configured your network with lnet you probably want to adjust the configuration manually.\par
+
+The network configuration file for your Lunar installation may be found in /etc/config.d/network/'interface' (f.e. 'eth0' $\rightarrow$ /etc/config.d/network/eth0). Any time you adjust your interface's configuration manually or through lnet you will have to restart the network to make use of any changes that have been done in the meantime. The init script used to start/stop/restart network is /etc/init.d/network.\par
+
+ \begin{lstlisting}
+ /etc/init.d/network restart
+\end{lstlisting}
+
+Good luck and please remember that you have to be able to ping f.e. 'google.com' to install any other packages or update your system!
+
+\subsection{Core Updates and Setup}
+
+Since Lunar Linux is a source based distribution, some of the binaries and/or modules on the CD may have been upgraded to newer versions already. Here are the first steps you should take to get an up-to-date, smoothly running and fast system:\par
+
+\subsubsection{Update your coretools}
+
+\begin{figure}[h]
+\begin{center}
+\includegraphics[width=0.8\textwidth]{./image/install12.pdf}
+\end{center}
+\caption{Gui of the \lstinline{lunar} coretool}
+\end{figure}
+
+You need to get the most recent version of the available coretools. The coretools are the heart of every Lunar Linux system. They provide you with all the necessary commands to maintain a working installation thus it's always recommended to have the latest version installed. There are two different choices:
+
+\begin{itemize}
+\item lunar
+\item theedge
+\end{itemize}
+
+lunar is the stable branch of the lunar coretools. It's ment to run with stable production environments. theedge is the unstable branch. It might occasionally contain bugs, however it's generally used to test out new features and bugfixes before they're migrated to the stable branch. If you'd like to help out with the lunar development or you discovered a bug in lunar you might want to give theedge a try.\par
+
+Since the ISO ships with theedge preinstalled you have to update theedge before you do anything else .. even if you're planning to use lunar lateron !
+
+\begin{lstlisting}
+ lin theedge
+\end{lstlisting}
+
+ If you want to keep Lunar Linux as stable as possible you need to install the stable coretools branch now by running
+
+ \begin{lstlisting}
+lin lunar
+\end{lstlisting}
+
+\subsubsection{ Core Components}
+
+ A very brief explaination of the most important coretool components is given here. Further information regarding the referenced parts please refer to their manpages (i.e. \lstinline{man $PART }) or the next chapter of this book:
+
+\begin{itemize}
+
+ \item lin; usage:\lstinline{ lin $MODULE} \\ Install a package/module.
+
+ \item lvu; usage: \lstinline{lvu $OPTIONS $MODULE} \\ Gather information about a package/module.
+
+\item lrm; usage: \lstinline{lrm $MODULE } \\ Remove a package/module.
+
+\item lunar; usage:\lstinline{ lunar $OPTIONS} \\ Lunar configuration utility
+
+\end{itemize}
+
+\subsubsection{ Update your moonbase}
+
+The package repository from where the coretools gather their package information is called moonbase. Also, packages are usually referred to as modules. Since the moonbase on your installation is probably outdated it's strongly recommended to update your moonbase right after your coretools.\par
+
+\begin{lstlisting}
+ lin moonbase
+\end{lstlisting}
+
+\subsubsection{ Set your preferences}
+
+ Lunar Linux can easily be customized and is highly configurable. For changing the options that affect your system you may use the menu driven \lstinline{ lunar} configuration utility. It's based upon ncurses which means you can even run it in the console of your choice. You need to become root to use it.\par
+
+\paragraph{Optimizations}
+
+Set the right optimizations for your computer. Beware that changing your optimizations to the wrongly values might actually break your whole installations so be really carefull about what you're chosing. The ISO has been built with a minimum of available optimizations to ensure the highest amount of flexibility. To see wether or not your processor supports a certain feature try a cat /proc/cpu. It usually shows the available settings that suit your machine.
+
+\paragraph{Integrity checking}
+
+Lunar is performing a range of security checks on tarballs and installed packages to prevent faulty tarballs and possible intruders from taking over your system. It also ensures that none of your currently installed packages is broken\par
+
+You may select the amount of checks from the Integrity checking submenu at the Options menu. It's generally recommended at least chose \lstinline{FIND_CHECK} and \lstinline{LDD_CHECK}. \par
+
+\paragraph{Feature menu}
+
+ As mentioned before, Lunar is highly configurable. Thus you have a whole menu to select its features from. It's strongly advised to at least take a look at it and get used to them. Explanations are usually displayed as soon as you select an item. \par
+
+\paragraph{Apart from that}
+
+Take a look at the lunar configuration tool. It can be a powerful companion while achieving the goal of setting up your system. \par
+
+\subsection{General Updates}
+
+Right now you're set to update your whole system. Before you do that make sure you have the most recent coretools and moonbase installed. \par
+
+The next step \textbf{can be omitted} ... however, it is highly recommened that you rebuild the following modules in the right order to ensure that your system is working right. \par
+
+ Here we go:
+
+\begin{lstlisting}
+lin -cr gcc glibc gcc bash coreutils tar wget
+\end{lstlisting}
+
+Explanation:
+
+\lstinline{lin} is obviously used to install a module. It also accepts multiple modules in a row. The '-cr' switch means 'compile (c)' and 'reconfigure (r)'. They're explained at the manpage. One needs to update gcc thus the first gcc statement. Right after that one should recompile glibc to ensure that it's working well with the latest compiled gcc. And finally gcc again to make use of the newly compiled glibc. The modules right afterwards are used by Lunar Linux itself thus they need to be up-to-date and compiled against the latest available gcc and glibc. \par
+
+\subsubsection{A complete update}
+
+Now, to update your whole system you need to issue the following
+
+\begin{lstlisting}
+ lunar update
+\end{lstlisting}
+
+It's going to compare your system's installed modules against the moonbases' definitions and update the installed modules accordingly. It's going to give you a list of modules that are going to be updated. If you're not sure wether you want a certain module to be updated remove it from the list. Once you're done the coretools are going to start the update which usually is going to take a very long time on a freshly installed system since most of its components will probably be outdated. So grab a coffee and/or a book and wait for it to finish ;-) \par
+
+Once it is done it is going to present you with a summary about how many module where successfully updated and which of them failed. \lstinline{lvu activity} is going to show you which of them failed and usually why. \lstinline{lvu compile $MODULE } is also going to show you the compilation's logfile which should clearly point you to the error that led to the failure of the module's compilation.\par
+
+The first thing to do would be to 're'lin' (i.e. execute \lstinline{lin -c} once more. It is always advised to use the -c and the -r switch incase a module fails to compile) all the failed modules by hand. If you think you will not be able to resolve the matter on your own you can still file a bugreport at the Lunar Linux bugtracker or report the error to the Lunar Linux mailinglist. For further information contacting us see chapter \ref{comty} \par
+
+Once the update has been completed successfully you may go ahead and customize your installation to suit your own needs.\\
+ Well done! \par
+
+
+\subsection{\lstinline{lunar}}
+
+
+\subsubsection{Profiles}
+ how to update install uninstall typical tasks, introduce profiles,
+
+\section{Important Packages}
+ xorg, kde, gnome, xfce, openoffice, mail clients \\
+this serves as a reference to users who ask for example. what email proggie shall i choose. just an overview over packages. this is has not to be desktop oriented. bs ?
+
+\subsection{ Xorg}
+
+\subsection{K Desktop Environment}
+
+\subsection{Gnome 2.6}
+
+\subsection{Xfce}
+
+\section{I found a BUG}
+
+If you found a bug in the Lunar Linux code, in a module or in the coretools, please fill out a bugreport on the website: \textit{http://bugs.lunar-linux.org}
\ No newline at end of file
Added: lunar-doc/trunk/lunar-manual/3troubleshooting.tex
===================================================================
--- lunar-doc/trunk/lunar-manual/3troubleshooting.tex 2005-07-06 17:27:25 UTC (rev 15617)
+++ lunar-doc/trunk/lunar-manual/3troubleshooting.tex 2005-07-07 00:56:56 UTC (rev 15618)
@@ -0,0 +1,278 @@
+\chapter{Troubleshooting} \label{tshoot}
+
+\section{Solving Linux Problems}
+
+Lunar Linux is a community project. As the community is rather small compared to other distributions, we don't have an all in one solution for everything. This has the advantage that in many aspects you are dealing with a more pure Linux, which means Lunar doesn't hide the complexity of the system from you with an "easy to click" setup tool; Its ideal suited to learn a lot of things about Linux. But what to do if things doesn't work ?
+
+\subsection{RTFM: \textbf{R}ead \textbf{T}he \textbf{F}riendly \textbf{ M}anual}
+
+If you are experiencing an error during the installation or use of a software package, take a close look into the manuals. On the commandline a
+
+\begin{lstlisting}
+ man COMMAND
+\end{lstlisting}
+
+can give you extensive help on a command. \par
+
+You will find further documentation in \lstinline{/usr/doc/%MODULE }. As the compilation takes place in \lstinline{/usr/src/\$MODULE}\footnote{Refer to Section \ref{inside} to understand this} , you will find some information there too. Further you can surf to the webpage of the project. You will find it by
+
+\begin{lstlisting}
+lvu info $MODULE
+\end{lstlisting}
+
+You can also take a look at section \ref{faq}
+
+\subsection{Ask the Internet}
+
+If you got an error message from your problem or a log entry, simply copy paste it into your favourite search engine. Often people are experiencing the same problems and solutions exist somewhere on the web. This will take some time, but will lead to success and knowledge in most cases.
+
+\subsection{Ask the Community}\label{comty}
+
+If you can't find a solution by doing this you can ask the community. You have different options doing this
+
+\begin{itemize}
+\item Write to the forum. It is located at \textit{lunar-linux.org} under "feedback"
+\item You can ask the Lunar Linux mailinglist. Subscribers are welcome under \textit{http://foo-projects.org/mail-man/listinfo/lunar }
+\item Ask the Lunar Linux developers in \textit{\#lunar} on a freenode irc server. You can use the modules \lstinline{xchat }or \lstinline{bitchx }for this.
+\end{itemize}
+
+\textbf{Note} This is a small community and most developers are rather busy. So please don't bug them until it bleeds. If nobody answers you in the chat, come back another day and use the other methods stated above to find a solution.\\
+\textbf{Note} Asking someone else is the way to learn less about an error. So this should be the last option for you to choose.
+
+\section{Frequently Asked Questions}\label{faq}
+
+\subsection{Compiler optimizations}
+
+\paragraph{Q: how do I set these optimizations?}
+
+just run \lstinline{lunar optimize}. You'll be taken through an interactive menu that explains all the options. Remember, optimize safely!
+
+\paragraph{Q: What are the recommended safe optimizations for lunar linux?}
+
+The default sure fire optimizations that are recommended are:
+
+\begin{itemize}
+\item C: -pipe
+\item C++: -pipe
+\item CPU Architecture: you should pick \textbf{ your } own system architecture (default to x86 for most people).
+\item Basic Optimzations: Fast (-01) but most people will opt in for Faster, or Fastest (fastest doesn't work on all systems, i.e. k6).
+\item CPU: Obviously your own cpu, or the cpu of the machine you plan to run this install on. (If you want to be able to run this install on many machines, you should be safe with I586).
+\item Speed Optimizations: If you want to be 100 \% sure that there won't be optimization problems you shouldn't select any of these.
+\item Extra features: I wouldn't recommend using any of these optimizations (only on modules know to be able to handle them), since they cause many apps to break.
+\item Floating Point Math: None (if your arch is x86 and you don't own a 386SX and 486SX, it's safe to go with x387).
+\item Linker options: Strip.
+\item Addon program support: CCache (make sure to install it first).
+\end{itemize}
+
+\textbf{ Note}: These settings should work for almost everyone, and there is a lot room for pushing these optimizations more (at the risk of problems with apps). Read "info gcc" and make sure you understand a given optimization \textbf{before} you enable it!
+
+\paragraph{Q: What optimizations are known to cause problems?} \par
+
+Some optimizations that are known to cause problems on x86 with many apps (even a entire system):
+
+\begin{itemize}
+\item -funroll-loops
+\item -fstrict-aliasing
+\item -ffast-math
+\item -ffloat-store
+\end{itemize}
+
+\textbf{Note}: These are sorted from the least unstable to most unstable. Read \lstinline{info gcc} and make sure you understand a given optimization \textbf{Before} you enable it!
+
+\paragraph{Q: What optimizations can I use to gain some speed but without major risks?} \par
+
+Start with the basic optimizations in the question "What are the recomended safe optimizations for lunar linux?" and change the Basic Optimizations to Faster (Fastest if you know that gcc will generate correct code for that cpu). -O2 obviously takes more compile time than -O1, and -O3 takes the most time to compile. Then select the cpu you will run it on. Some of the speed optimizations that should be decent and shouldn't cause too many problems (if any) are: -fomit-frame-pointer. A safe bet for floating point math on a x86 would be x387 (if you know your cpu has a floating point unit). Check \lstinline{cat /proc/cpuinfo} to see if your cpu supports SSE or SSE2. If your cpu does have sse or sse2 then you can also add that to the math optimizations.
+
+\textbf{Note}: These are sorted from the least unstable to most unstable. Read \lstinline{ info gcc} and make sure you understand a given optimization \textbf{Before} you enable it!
+
+\paragraph{Q: What optimizations should I stay away from?} \par
+
+All the ones listed in the Question "What optimizations are known to cause problems?" plus:
+
+\begin{itemize}
+\item -fprofile-arcs
+\item -fbranching-probabilities
+ \end{itemize}
+
+Note:Read \lstinline{info gcc} and make sure you understand a given optimization \textbf{ before} you enable it! The Lunar-Devs have no sympathy for bug-reports of the nature "Why can't I compile a given module, when my optimizations are: (long list of \textbf{unsafe} optimizations!)"
+
+
+\subsection{Installing modules}
+
+Some modules (how we call packages that are installable by lunar-linux) have problems or require you to perform specific actions yourself.
+
+\paragraph{Q: Can I install multiple modules at the same time?} \par
+
+You can, lunar promotes it even! However it makes installs go slower of course. Lunar will not install things as important as gcc / glibc while something else is going on and will wait until the rest is finished. Complementary, you cannot install applications while those major apps are installing, they will wait their turn until it's safe to install them automatically.
+
+\paragraph{ Q: configure: error: C preprocessor /lib/cpp fails sanity check ?} \par
+
+Your kernel headers are missing from /usr/include. This means the C PreProcessor cannot verify that it has the proper cached copies of those vital header files. You need to install the proper ones manually. Here's how:
+
+\begin{enumerate}
+ \item \lstinline{ lin kernel-headers-2.4} might work for you! (Use the 2.6 version if needed of course)
+ \item Otherwise: \lstinline!mkdir -p /usr/include/{linux,asm}! to create the two target dirs, if needed. Then execute:
+
+\begin{lstlisting}
+cp -av /usr/src/linux/include/linux /usr/include/
+cp -av /usr/src/linux/include/asm/* /usr/include/asm/
+\end{lstlisting}
+
+ to copy the files manually. Be warned that the second command has to be done this way since /usr/src/linux/include/asm is a softlink to your arch asm header files (asm points to asm-i386, on x86 machines). So if, on the other hand, you had copied
+
+\begin{lstlisting}
+cp -av /usr/src/linux/include/asm /usr/include/
+\end{lstlisting}
+
+ you would then get a softlink to nowhere under /usr/include/.
+
+\item Last, you can always try to unpack the kernel tarball you have into /usr/src/linux and manaully link or copy the headers over yourself.
+\end{enumerate}
+
+ \paragraph{Q: how do i add other window managers to the sessions on gdm i'd like to get kde and xfce setup} \par
+
+copy the desktop startup files to \lstinline{/etc/X11/dm/Sessions/}. That works with gdm. For kdm you will have to copy them to \\ \lstinline{$KDE_PREFIX/share/apps/kdm/sessions}
+
+ \paragraph{Q: How do I get Flash to work with mozilla ?} \par
+
+If you are using mozilla, then you can simply do a \lstinline{lin flash-plugin} and that will download and install the Macromedia Flash plugin that works with a gtk+ based mozilla through the old abi wrappers. \par
+The flash plugin does \textbf{not} work with Galeon. Galeon developers have declined to provide the "old" abi wrappers needed for the plugin to work.
+
+ \paragraph{Q: How do I get Java for my Lunar box ?} \par
+
+You have to download the java source code from Sun yourself and you have to "click" to agree on their license. You have to compile it yourself too.
+We don't have a Sun Java module as we currently have no way to automate the "click" to agree to the Sun Java license.\par
+
+See this URL for some handy info:
+\begin{center}
+\textit{http://www.linuxfromscratch.org/~tushar/hints/javafromscratch.txt}
+\end{center}
+
+There is a j2sdk module in moonbase which is the Blackdown port of Sun's Java Virtual Machine.
+
+
+\subsection{Lunar core tools}
+
+
+ \paragraph{Q: How do i force lunar to recompile my modules with different options?} \par
+
+Try:
+
+\begin{lstlisting}
+lin -r MODULE
+\end{lstlisting}
+
+-r means: Select new configuration and dependencies for modules.\par
+Check the man page (\lstinline{man lin}) for all available switches.
+
+\paragraph{Q: How do I tell lunar to recompile my application instead of resurrecting it?} \par
+
+Try doing:
+
+\begin{lstlisting}
+lin -c MODULE
+ \end{lstlisting}
+The -c option means: Compile this module even if there is an install cache copy available in /var/cache/lunar.\par
+
+Check the man page (\lstinline{man lin}) for all available switches.
+
+\paragraph{Q: My moonbase is gone and now I can't install any modules?} \par
+
+Simple solution to this is just running:
+
+\begin{lstlisting}
+lin moonbase
+ \end{lstlisting}
+
+This will download the latest moonbase from the internet, and restore it to working order.\par
+
+Check the man page (\lstinline{man lin}) for all available switches.
+
+\paragraph{Q: What is a module?} \par
+
+A \textbf{module} is a set of files that tell the core tools the following:
+
+\begin{itemize}
+ \item What name, version, and other properties a package has
+ \item Where to download all needed source files
+ \item What other modules are required, or conflict with this one
+ \item How to unpack the source files, how to patch
+ \item How to configure the code
+ \item How to compile
+ \item How to install everything
+ \item What else to do with it
+ \end{itemize}
+
+The module is coded in a set of files in a directory structure, and programmed in bash.
+
+\paragraph{Q: What is moonbase?} \par
+
+\textbf{moonbase} is a database with modules. In this database there are description of packages that tell the core tools where to download, how to install etc... You can consider this the lunar equivalent of portage, grimoire, ports etc.
+
+\paragraph{Q: What is theedge?} \par
+
+\textbf{theedge} is the same as \textbf{lunar}, and also known as the core code. Theedge is just another version of lunar. These two pieces of code install your packages, but they do not contain package descriptions. Those are defined in moonbase.\par
+
+Theedge is a development version of lunar. Often there are much more features in theedge, and bugs are fixed quicker as well. However, if you do not like all this tweaking on your system, we advice you to use the stable lunar core tools instead on your system.\par
+
+You can install theedge by issueing:\\
+
+\begin{lstlisting}
+lin theedge
+ \end{lstlisting}
+
+Theedge automatically is updated if you do a \lstinline{lunar renew } or \lstinline{lunar update}
+
+
+\subsection{Lunar-Linux Installation}
+
+Commonly asked questions about the lunar installation process.
+
+\paragraph{Q: Kernel features, built-in or module?} \par
+
+There are many schools of thought on kernel compiling. One school is to build everything into the main kernel without modules. The other one school takes building modules to the extreme. I have this rule, if it's not needed to boot it's a module. Thus usb, input, sound, mice ACPI, network, and also cdrom (cdrw anyone?) floppy, and all the non boot file systems (everything except XFS and ext2), all get built as modules. This reduces the size of the main kernel so it can be put on a disk. Another thing to consider is that not everything works perfectly, and some features can cause your kernel too misbehave. So if some feature is built-in, the bad behavior is practically inevitible. While with a module you can choose not to load it and thus be left with a working system. These are just my tips (Dem). Use whatever works for you.\par
+
+\textbf{Note}: Some people need to make some features built into their kernel and vice versa, do whatever works best for you.
+
+\paragraph{QEMU and Lunar ISO testing} \par
+
+Just a quick note on how to use qemu for testing a Lunar Linux installation. See moonbase/devel/qemu/DETAILS for a description of qemu. Think of it as a low-cost (read: free) version of vmware, that has quite a few useful features and is under active development.\par
+
+A very simple way to just test a Lunar ISO for booting purposes is:
+
+\begin{lstlisting}
+qemu -cdrom lunar-20040309-2.iso -boot d
+\end{lstlisting}
+
+If you want to test a full install, then create a 512Meg sparse \lstinline{ root_ fs image} with this dd command:
+
+\begin{lstlisting}
+dd if=/dev/zero of=root-qemu-fs bs=\$((1024 * 1024)) count=0 seek=512
+\end{lstlisting}
+
+Now invoke qemu:
+
+\begin{lstlisting}
+qemu -cdrom lunar-20040309-2.iso -boot d -hda root-qemu-fs
+\end{lstlisting}
+
+and you can then proceed to test your Lunar 1.4.0 install.\par
+See the qemu homepage for further tips and tricks. qemu can also be quite easily used to test if your brand new kernel is bootable or not (this is really slick). \par
+
+\textbf{Note}: say yes to using SDL as an \lstinline{optional_depends}. The gui version of qemu is \textbf{very}nice in its own little X11 window!
+
+\subsection{Other}
+
+\paragraph{Q: How do I unpack a XYZ.rpm file in lunar ?}\par
+
+he easiest way to unpack a rpm file is to use the provided program called rpmunpack. Simply run: \lstinline{rpmupack XYZ.rpm}. This will create a cpio file (\lstinline{XYZ.cpio.gz} and \lstinline{XYZ.cpio.bz2} are not uncommon). Once you perform any additional uncompression (gunzip or bunzip2), you can then extract it using cpio: \lstinline{cpio -i -d < XYZ.cpio} . After all that you should be all done. If you are trying to \lstinline{rpmunpack} a \lstinline{.src.rpm} file then \lstinline{XYZ.cpio} may further contain a tar.bz2 or tar.gz source tarball.
+
+In the zbeta section of moonbase, there is an \textbf{unsupported } module called \lstinline{rpm} for those of you that are really desperate!
+\textbf{Note}: You might want to do \lstinline{man cpio}, to check out additional cpio parameters such as -L.
+
+
+\paragraph{What is that logo of yours?}\par
+
+The logo is a rock hopper penguin. It's a kind of nasty penguin, the one that crowd up in thousands to take over the continent. They have a few long feathers sticking out at their 'ears' sideway, just like some owl species do.\par
+
+You can check out Google Images for lots of "rock hopper penguin" pictures!
\ No newline at end of file
Added: lunar-doc/trunk/lunar-manual/4inside_lunar.tex
===================================================================
--- lunar-doc/trunk/lunar-manual/4inside_lunar.tex 2005-07-06 17:27:25 UTC (rev 15617)
+++ lunar-doc/trunk/lunar-manual/4inside_lunar.tex 2005-07-07 00:56:56 UTC (rev 15618)
@@ -0,0 +1,102 @@
+\chapter{Inside Lunar Linux} \label{inside}
+more detailed
+\section{Core Tools}
+docu of lin lvu lunar etc etc
+much more detail than above.
+\subsection{$lin$}
+\subsection{$lvu$}
+
+\subsection{Admins Tiny Little Helpers}\label{tlhelp}
+\paragraph{lservices}\label{lserv}
+\paragraph{lnet}\label{lnet}
+
+ lsevices, luser etc etc ?
+
+\section{Handling /dev Devices}\label{devnode}
+
+\subsection{A little background}
+
+Every box needs a set of device node in order to work. Currently there are 2 ways of creating these nodes: statically or dynamically. \par
+
+\subsection{Static device nodes}
+
+/dev content is permanent, on a real permanent filesystem (like ext3, XFS, reiser...). All the needed nodes are present, or are created with a mknod command. You can also create nodes with the makedev utility. \par
+
+\subsection{Dynamic device nodes}
+
+Nodes are created from hotplug events, e.g., on the fly. Here, depending on your kernel, you have 2 choices:
+\par
+
+\subsubsection{devfs}
+devfs' device nodes are created in kernel space, on a virtual fs. It is therefore part of the kernel tree source.
+
+\subsubsection{udev}
+
+udev's device nodes are created in userspace, and by a userland application, thus outside the kernel tree. udev can lie on any filesystem, permanent or not, but due to its nature, is normally on a virtual filesystem, like ramfs - this is Lunar's case. \par
+
+Altough devfs is still currently in 2.6 it "will be removed real soon" (TM). So basically we can think of 2 defaults: for 2.4, devfs is mainly used; on 2.6, udev will be mainly used. A smaller portion of users still have static (on real fs) nodes. \par
+
+\paragraph{What commandline options can be used}
+
+To tell Lunar what type of device nodes I want to use there is a commandline switch that is dev=, that can take 4 values:
+
+\begin{itemize}
+\item dev=static
+\item dev=devfs
+\item dev=udev
+\item no commandline whatsoever
+\end{itemize}
+
+The options are quite self explaining. A good thing to take in mind is that they behave differently depending on your kernel.
+
+\subsection{2.4 kernels}
+
+valid dev= values are:
+
+\begin{itemize}
+\item dev=devfs
+\item dev=static
+ \end{itemize}
+
+If dev=udev was passed to a 2.4 kernel on boot, a warning message will be displayed, and it will fallback to normal 2.4 behaviour: if no dev= commandline has been supplied, or its value is not correct, it shall fall through:
+
+\begin{itemize}
+\item Test for dev=devfs, and if devfs' binary is there, try to boot with it.
+\item If there's no devfs installed, boot as if a static dev was present.
+ \end{itemize}
+
+\subsection{2.6 kernels}
+
+valid dev= values are:
+
+\begin{itemize}
+\item dev=udev
+\item dev=devfs
+\item dev=static
+ \end{itemize}
+
+And are tested in exactly this order if no valid dev= is supplied or no commandline is supplied whatsoever.
+
+\subsection{Adding the params: bootloaders}
+
+\subsubsection{lilo}
+
+To add a commandline param in lilo, you have to use the append label. Taking dev=udev as an example:
+
+\begin{lstlisting}
+image=/boot/vmlinuz label=awesomekernel root=/dev/hda2 append="dev=udev video=radeonfb:1152x864-16 at 60"
+\end{lstlisting}
+
+If you have prompt set in your lilo.conf, you can even write the option just before the kernel you want loads.
+
+\subsubsection{grub}
+
+To add a commandline param in grub, all you have to do it put it behind the kernel placement, on the kernel label's line:
+
+\begin{lstlisting}
+title awesomekernel
+root (hd0,1)
+kernel /boot/vmlinuz root=/dev/hda1 dev=udev video=radeonfb:1152x864-16 at 60
+\end{lstlisting}
+
+Don't forget that in grub you can edit the kernel label line on boot.
\ No newline at end of file
Added: lunar-doc/trunk/lunar-manual/5getting_to_work.tex
===================================================================
--- lunar-doc/trunk/lunar-manual/5getting_to_work.tex 2005-07-06 17:27:25 UTC (rev 15617)
+++ lunar-doc/trunk/lunar-manual/5getting_to_work.tex 2005-07-07 00:56:56 UTC (rev 15618)
@@ -0,0 +1,308 @@
+\chapter{Getting to work ...}
+
+\section{Kernel 2.6}
+
+ \paragraph{What's this 2.6 kernel hoo-hah about anyway?}
+
+The Linux kernel version 2.6 is the current stable Linux kernel. Although Lunar Linux is a bleeding edge distribution, we do not think that a jump to a full 2.6 install is a good idea for production servers yet. A desktop can run comfortably on 2.6, but if you are a newbie, we strongly recommmend you starting off with 2.4. If you still think about going ahead, having a bootable fall back 2.4 kernel is useful, specially when you configure a 2.6 kernel for the first time. \par
+
+Having said that, and keeping it in mind, we will describe how to install a 2.6 kernel, using our lunar kernel module called linux-2.6 (that only holds stable kernel.org releases). Although we are going to use linux-2.6 here, this can be applied for any other of our linux-2.6 set (currently linux-2.6-ck, linux-2.6-grsec, linux-2.6-inotify, linux-2.6-mm and linux-2.6-prepatch).
+When did this all come about?\par
+
+The 2.5 kernel became grown up on the 18th of December 2003, when the stable 2.6 tree was released. Before that, since April 2003, we have had a 2.6 module in moonbase.\par
+
+ \paragraph{Who wrote all this fine software?}
+
+The main 2.5 and the later 2.6 trees have been maintained by \textbf{Linus Torvalds}. This responsability is now in hands of \textbf{Andrew Morton}, who for testing purposes keeps his own set of patches against the 2.6 tree. The patches' names are suffixed with -mm. A Lunar module with the mm patch is available, though not recommended for first 2.6 installs. If you have a problem with the current served kernel in linux-2.6, linux-2.6-mm maybe a temporary solution. Once tested, the features that are doing fine in mm patches are merged into the main 2.6 tree, so if linux-2.6-mm works now, it is very likely linux-2.6 will as well very soon.
+Why would I want to switch away from my 2.4 kernel?\par
+
+The first time I tried a (then) 2.5 kernel, I did so because of curiosity. I wanted to feel directly how this new thing ran. I've hardly ever stopped using it since then. If you have an X server running on your 2.6 kernel, the first thing that you'll notice is your mouse speed skyrocket. The responsiveness of the X apps has taken a huge step forward. This is only one of the many new features you will find in the 2.6 series.\par
+
+Apparently, there has been a focus on server side, though the average user should be pleased, as exampled above with X. PDA and embedded linux users should be happy, too.\par
+
+From server side, the leap from the 2.4 to the 2.6 kernel is more than a simple version change:\par
+
+\begin{itemize}
+\item 64 Bit
+\item NUMA ( Non-Uniform Memory Access ): For clusters with a high amount of nodes, memory sharing is vital. NUMA adresses this problem.
+\item Better performance under heavy loads: Many benchmarks demonstrate 2.4 is completely outperformed. High payload environments are webservers and databases, for example.
+\item The addressing space for unique users is no more 16 bit but 32 bit. so the user support has grown to 4 billion from 65,000.
+\item Hyper-Threading: Intel's P4 and Xeon servers support multiprocessor emulation, although they really only have 1 processor.
+\item Higher limits: PIDs (process IDs) have grown from 32,000 to 1 billion, RAM's max is now 64 GB instead of 4 GB, and filesystem's top is set at 16 Terabytes, instead of 4.
+\item Higher bandwidth network support.
+ \end{itemize}
+
+Desktop/laptop have had their share of new features as well:
+
+\begin{itemize}
+\item ALSA (Advanced Linux Sound Architecture) has been merged in the kernel tree and it has better joystick support.
+\item Broader wireless and native Bluetooth support.
+\item Software suspend-to-disk and speed scaling for laptops.
+\item Samba protocol update, to interact better with Windows environments.
+\end{itemize}
+
+Embedded systems have also been taken care of
+:
+\begin{itemize}
+\item uCLinux support.
+\item Support for more types of MMU-less processors, like PDAs, for example.
+\item Embedded Profile support.
+\end{itemize}
+
+At least the first 2 (servers and desktops/laptops) will benefit from some other upgrades:
+
+\begin{itemize}
+\item New scheduler: optimization of system resources, no matter if you have 1 CPU or you have many.
+\item Better I/O scheduler, faster read/writes.
+\item NFS (Network File System) upgrade, supporting NFSv4, cryptography and higher loads.
+\item ext3, xfs journalised filesystems.
+\item Native USB 2.0 support.
+\item* IPSec: IP Security protocol
+\end{itemize}
+
+Those most probably are not all, but I suppose you can get a slight idea on how things have changed. Remember that 2.6 kernel is fairly young.\par
+
+\paragraph{Where would I want to install it? }
+
+Starting from the features listed above, the 2.6 kernel would be suited from any machine like a big cluster, SMP machine, down to desktop a or something as small as a handheld. But I have my own case to show you that 2.6 kernels work. I have 2 desktops and a server, all 3 with 2.6 kernels and fully 2.6 installs, and I must say I have no complaint. Don't think I'm alone here, since I have friends that I have helped install 2.6 kernels (no big deal, as you will see), or they have done so by themselves on their desktops, laptops or servers. They didn't worry about if their hardware was the oldest or brand new, they jumped anyway. The news I have is that they are quite happy. Sum up Lunar users and fellow Lunar devs, and I know a good lot running 2.6 kernels. And you are hopefully next :)
+Okay. I'm convinced. How do I install this thing? \par
+
+Before you do anything else, I'd recommend you take your time to do the switch, because changing from a 2.4 tree to a 2.6 tree kernel is not so simple as compiling a 2.6 kernel with your 2.4 .config. \textbf{Please don't rush!} \par
+
+\paragraph{Installing the Kernel}
+
+The first stage of a jump to a 2.6 kernel install would be to install the latest available in moonbase; the second stage would be setting all your Lunar install to be 2.6 based, recompiling each Lunar module against 2.6 headers, but you need not worry about that, if you don't want to -it is not necessary, though it will be explained. By the way, you can still run a 2.6 kernel in a 2.4 header environment, if you just want to give it a small test. \par
+
+To install the last 2.6 kernel from moonbase all you have to do is to install the linux-2.6 Lunar module. You will start the compile from a default .config the kernel tarball brings, since the difference between 2.6's config and 2.4's is too big to import your current 2.4 kernel configuration -in some cases it has even been problematic. I again here strongly recommend walking through the whole kernel's configuration. This is important because the configuration's hierarchy tree has changed a lot: things have been moved, others taken out, and new features have been fitted in (that you might want to know). \par
+
+Now let's get to the nitty gritty of it, and do the install itself. As root:
+
+\begin{lstlisting}
+root at myshinybox ~ # lin linux-2.6
+\end{lstlisting}
+
+will fetch the sources and prepare the build. As a dependency, the module-init-tools Lunar module will be installed, because it is needed for kernel module management (as the modutils Lunar module is needed for 2.4 kernels). \par
+
+Now you will be asked a few questions, first of all about your bootloader:
+
+\begin{flushleft}
+linux-2.6: Configure this kernel to load from grub? [n]
+\end{flushleft}
+
+If you answer 'y', an entry will be added to grub's menu.lst file, and you will be prompted with another question after:
+
+\begin{flushleft}
+linux-2.6: Configure grub? [n]
+\end{flushleft}
+
+If you say no, grub will be handled automagically. If you say yes, you will have to configure grub yourself after the kernel build. If, on the other hand, you said no to the "Configure this kernel to load from grub" question, you should see, analogously to grub:
+
+\begin{flushleft}
+linux-2.6: Configure this kernel to load from lilo? [n]
+\end{flushleft}
+
+Answer yes ('y'), if you wish to use lilo as your prime bootloader. \par
+
+If you answered yes to the lilo question, you should be prompted just like grub:
+
+\begin{flushleft}
+linux-2.6: Configure lilo? [n]
+\end{flushleft}
+
+Once again, if you say 'y' (yes) you will have to hand configure lilo.conf after the kernel build has finished. If you said no, lin will take care for you. For now, a safe answer is say no to bootloader configuration, so Lunar takes care of your grub or lilo. \par
+
+Next step to cope with is what interface we are going to use to configure the kernel:
+
+\begin{flushleft}
+linux-2.6: Do you prefer xconfig over menuconfig? [n]
+\end{flushleft}
+
+If you want to use \lstinline{xconfig}, answer 'y'. If you prefer any other answer 'n'. If you answer 'n', you will have one more question on this topic:
+
+\begin{flushleft}
+linux-2.6: Do you prefer menuconfig over config? [y]
+\end{flushleft}
+
+Unless you really know what you are doing, say 'y' to use a ncurses interface \lstinline(make menuconfig) and not use a questionaire method \lstinline(make config). Any other answer than 'y' will lead you to make config. \par
+
+Finally, you will see one last question:
+
+\begin{flushleft}
+linux-2.6: Configure linux kernel? [n]
+\end{flushleft}
+
+As it is your first encounter with linux-2.6, please answer 'y', so you walk the whole kernel config (remember, it is important to walk to whole lot!). \par
+
+Now that questions have been dealt with, the source will be downloaded. Once the download finished, the source has been unpacked, and the build began, your interface of choice to the kernel's configuration will be shown. Choose what you need for your box. \par
+
+After kernel configuration, you will be prompted one more time:
+
+\begin{flushleft}
+Repeat config? [n]
+\end{flushleft}
+
+If you think you missed something and you want to go back to kernel configuration, you are still in time; yet, if you are happy already, just say 'n', and watch your kernel build. You will prompted with this question every time you finish your config method. \par
+
+When the kernel has successfully built, two things may happen, depending on what you answered previously: if you have answered yes to configure your bootloader, you will see your bootloader's config file opened in an editor for you. A new kernel entry, for your new kernel will be there, so you can do some tweaking if you like. If you decided to let lin take care (answered 'n' to configure your bootloader), this will be done without your interaction. \par
+
+If walking the kernel's configuration you added pts support, you must remember to add a line to /etc/fstab in order to have it mounted at boot time:
+
+ \begin{lstlisting}
+devpts /dev/pts devpts defaults 0 0
+\end{lstlisting}
+
+Yay, done with the kernel! ;)
+
+\paragraph{udev and sysfs}
+
+udev is a new feature in 2.6. It brings dynamic userspace dev nodes, the equivalent in userspace of what devfs did in kernel for 2.4. Udev is based on another new feature: sysfs. Sysfs is a virtual filesystem, that lists system information in a hierarchical way (like a boosted proc, so you can get the idea). Both udev and sysfs, unlike other features in 2.6 that have been backported, are not seen in 2.4 kernels. \par
+
+There is no fixed reason why you should install udev, though it will simplify a lot your work, so we do recommend doing so. A good reason is that if you are used to using dynamic dev nodes, sooner or later devfs will be deprecated (it is already marked as such in the kernel) and will be droped out. Another solution is having a static /dev with permanent nodes, that you can hand create each time you need a new node, or create the whole lot of device nodes using the makedev Lunar module. \par
+
+udev uses hotplug to create the nodes under /dev, so it is completely independant from the running kernel. It uses namedev to set device naming policies, and libsysfs to query sysfs.\par
+
+To install udev, as root:
+
+\begin{lstlisting}
+root at myshinybox ~#\lin udev
+\end{lstlisting}
+
+will install udev, and sysfsutils and hotplug as dependencies. One thing you have to know about udev is that its use excludes the use of devfs. You can still have devfs support as a module but you must not enable "automatically mount devfs at boot" (see the kernel's Filesystems section, subsection pseudo filesystems). Furthermore, the kernel has to be hotplug aware, so this option should be included when compiling a kernel for udev (see General Setup -> Support for hot-pluggable devices).\par
+
+Yay, done with udev!
+
+\textbf{IMPORTANT NOTE}: At this point, whatever you choose as your /dev, please really read
+Chapter \ref{devnode} : Handling /dev Devices \par
+
+\paragraph{Rebuilding software against 2.6 headers}
+
+The possible second stage of a 2.6 migration would be rebuilding our software against 2.6 headers.\par
+
+Before explaining how to accomplish the 2.6 header based Lunar box, I will make one last warning: The Lunar Linux team does not officially support 2.6 installs. This is very important, because we currently do not do 2.6 specific fixes, if these collide with 2.4 only Lunar module setups (there are exceptions). If you come around any problem, please report it, as it will be taken in consideration, that is for sure. \par
+
+The process of switching is quite simple, really. There is a Lunar module that serves a series of sanitized kernel headers, kernel-headers-2.6, but everytime glibc is recompiled it creates a tarball from the headers under /usr/src/linux. So if the last kernel you installed was linux-2.6, you'll have a 2.6 headers tarball created from it and installed, if you recompiled glibc after installing your kernel. This is not true if you installed kernel-headers-2.6's Lunar module; glibc would still create the headers, but not install them. This is an exception to the Lunar's 2.6 non-support module scheme.\par
+
+For the sake of standarization, we recommend the install of kernel-headers-2.6. Bug tracking for you and for us will be simplified if we use the same set of headers. If each of us have our own headers with different versions, it would be harder to know if it is an app problem or a header problem. So, if you decide to take this step, and move to a fully 2.6 environment, please install kernel-headers-2.6. We all move forward together.\par
+
+Taking for granted you do want to install kernel-headers-2.6, as root type:
+
+\begin{lstlisting}
+root at myshinybox ~ \# \textit{lin kernel-headers-2.6}
+\end{lstlisting}
+
+Second step here is to rebuild your software against your new headers. This should be done in a certain order. As a base 2.6 install, from which later rebuild the rest of your apps, you should \lstinline{ lin}:
+
+\begin{itemize}
+ \item kernel-headers-2.6
+ \item gcc
+ \item glibc
+ \item binutils
+ \item coreutils
+ \item bzip2
+ \item gzip
+ \item tar
+ \item diffutils
+ \item findutils
+ \item make
+ \item grep
+ \item gawk
+ \item sed
+ \item gettext
+ \item ncurses
+ \item patch
+ \item texinfo
+ \item bash
+ \item util-linux
+ \item perl
+\end{itemize}
+
+Having done this, you will have a good base towards having a fully 2.6 install. From now on, you can rebuild in whatever order you want the rest of your installed Lunar modules so they as well are 2.6 based. \par
+
+Yay, done with headers! \par
+
+
+\subsection{Usefull Links}
+
+"Is Linux Kernel 2.6 Primed for the Enterprise?",
+http://www.enterpriseitplanet.com/networking/features/article.php/3321801
+
+"Linux 2.6.0: What's New"
+http://www.osdl.org/newsroom/press\_releases/2003/2003\_12\_18\_beaverton\_2\_6\_new.html
+
+\section{64-Bit Linux}
+
+\section{(A)DSL}
+
+\section{Printer}
+
+\section{USB Drives}
+
+\subsection{Apple's Ipod}
+
+Use gktpod ....
+
+\section{3D Acceleration}
+
+\subsection{Nvidia Accelerators}
+
+\subsection{ATI Accelerators}
+
+First you need to make shure, your kernel matches all requirements.\footnote{The following is taken from the fglrx howto found at www.rage3d.com written by Peter Gracar (who.knows AT email DOT si)} So do a \textit{lin -rc linux-2.X}, use your favourite tool to investigate kernel konfigurationand enable the following options:
+
+\begin{itemize}
+\item /dev/agpgart under ``character devices''
+\item MTRR (Memory Type Range Register) under ``processor type and features''
+ \end{itemize}
+
+Then disable:
+
+\begin{itemize}
+\item Direct Rendering Manager (XFree86 DRI support) under ``character devices''
+\item Kernel debugging under ``Kernel hacking''
+ \end{itemize}
+
+Thats it. We will asume the build-in AGPGart driver supports your mainboard. If you encounter error regarding ADPGart, please check the rage3d.com How-To. \par
+Further you need the fglrx module. Do a
+
+\begin{lstlisting}
+lin fglrx
+\end{lstlisting}
+
+and the newest module will be installed. To check if it was successfully loaded you can look if \lstinline{lsmod} shows fglrx. The next step is to configure XOrg for the driver. The module provides the \lstinline{fglrxconfig} wizard. It replaces your /etc/X11/xorg.conf by one customized for the fglrx driver. Now you should be up and running. By today the closed source drivers doesn't support the composite extension (shadows, transparency). If you want it, use the radeon open source driver. \par
+
+You can test 3d Acceleration by \lstinline{fglrxinfo} and set the gamma values by \lstinline{fglrxgamma}. For a GUI driven menu you can use \lstinline{fireglcontrol}. When running \lstinline{fglrxinfo }you should see something like that:
+
+\begin{lstlisting}
+root at Schroedinger / # fglrxinfo
+display: :0.0 screen: 0
+OpenGL vendor string: ATI Technologies Inc.
+OpenGL renderer string: MOBILITY RADEON 9600 Generic
+OpenGL version string: 1.3.5140 (X4.3.0-8.14.13)
+\end{lstlisting}
+
+\subsubsection{Troubleshooting}
+
+If you encounter problems, take a look at \textit{www.rage3d.com}. Under forum/linux/driver you will find a discussion of many users of this driver. Even ATI developers show up sometimes! You will also find a How-To there. \par
+Take a look if the symlinks in /usr/X11R6/lib/ :
+
+\begin{lstlisting}
+libGL.so -> /usr/X11R6/lib/libGL.so.1.2
+libGL.so.1 -> /usr/X11R6/lib/libGL.so.1.2
+ libGLU.so -> libGLU.so.1.3
+libGLU.so.1 -> libGLU.so.1.3
+ libGLw.so -> libGLw.so.1.0
+libGLw.so.1 -> libGLw.so.1.0
+\end{lstlisting}
+
+exist. \par
+For diagnostic, examine /var/log/Xorg.0.log, and look for entries with [EE] at the beginning.
+
+\section{WLAN}
+
+\section{Apache}
+just as an example
+
+\section{Openoffice}
+needed ? even oo-src here ?
+
+\section{Composite Extension, aka Eyecandy}
\ No newline at end of file
Added: lunar-doc/trunk/lunar-manual/6development.tex
===================================================================
--- lunar-doc/trunk/lunar-manual/6development.tex 2005-07-06 17:27:25 UTC (rev 15617)
+++ lunar-doc/trunk/lunar-manual/6development.tex 2005-07-07 00:56:56 UTC (rev 15618)
@@ -0,0 +1,386 @@
+\chapter{Development for Lunar Linux}
+most detailed. can only be writen by devs ... best : sofar; resources in svn for this ...
+
+\section{Development with Subversion}
+
+\section{Variables}
+
+\section{Places}
+
+\section{Modules}
+\subsection{Module Design}
+
+In lunar parlance, software packages are called modules. The collection of all modules is the moonbase, which is simply a directory (usually \lstinline{/var/lib/lunar/moonbase}) containing sections (i.e. directories) which in turn contain the module directories. \par
+
+A module is simply a directory containing the scripts necessary to build a software package, and optionally configuration files which may be needed in /etc. Some modules require only a DETAILS file, however this is only the case for a few of the modules in the entire moonbase. In each case (after \lstinline{DETAILS}, \lstinline{DEPENDS} and \lstinline{CONFIGURE}) where a module can use lunar's default internal function(s), there is no need for a module-specific script. \par
+
+\begin{itemize}
+\item \lstinline{DETAILS }sets version, source URL(s) and other critical data
+\item \lstinline{DEPENDS} specifies required and optional packages
+\item\lstinline{ CONFLICTS} specifies modules which must(will) be removed by module
+\item \lstinline{CONFIGURE} interactive script where build options can be set
+\item \lstinline{PRE_BUILD} most often used for patching, unpacking addional source tarballs
+\item \lstinline{BUILD} runs necessary variations on: configure; make; make install
+\item \lstinline{POST_BUILD} install configuration scripts and data.
+\item \lstinline{POST_INSTALL} messages, notes more cleanups, configuration fixes
+\item \lstinline{PRE_REMOVE} used by \lstinline'lrm'; actions which must preceed removal
+\item \lstinline{POST_REMOVE} used by \lstinline'lrm'; actions which must follow removal
+ \end{itemize}
+
+\subsection{Package Build and Install Scripts}
+
+The following scripts are used by \lstinline{lin} (or indirectly by \lstinline{lunar}) when building modules. \par
+
+\subsubsection{The DETAILS script}
+
+Every module is required to have at least a \lstinline{DETAILS} file. A minimal \lstinline{DETAILS} may appear as follows : (\lstinline{/var/lib/lunar/moonbase/editors/emacs/DETAILS}) \par
+
+\begin{lstlisting}
+ MODULE=emacs
+ VERSION=21.3
+ SOURCE=$MODULE-$VERSION.tar.gz
+SOURCE_DIRECTORY=$BUILD_DIRECTORY/$MODULE-$VERSION
+ SOURCE_URL=$GNU_URL/$MODULE/$SOURCE
+ SOURCE_URL=ftp://ftp.gnu.org/pub/gnu/$MODULE/$SOURCE
+ SOURCE_VFY=md5:a0bab457cbf5b4f8eb99d1d0a3ada420
+ WEB_SITE=http://www.gnu.org/software/emacs
+ ENTERED=20010922
+ UPDATED=20020529
+ SHORT="Emacs is the extensible, self-documenting real-time display editor."
+cat << EOF
+Emacs is the extensible, customizable, self-documenting real-time display editor.
+EOF
+\end{lstlisting}
+
+With comments, default values:
+
+\begin{lstlisting}
+ MODULE=emacs # Module name, yes it's redundant
+ VERSION=21.3 # Version, changes *often*
+ SOURCE=$MODULE-$VERSION.tar.gz # Source filename
+SOURCE_DIRECTORY=$BUILD_DIRECTORY/$MODULE-$VERSION # Where source unpacks # ($BUILD_DIRECTORY=/usr/src)
+ SOURCE_URL[0]=$GNU_URL/$MODULE/$SOURCE # Download URL
+ SOURCE_URL[1]=ftp://ftp.gnu.org/pub/gnu/$MODULE/$SOURCE # Alternate URL(s)
+ SOURCE_VFY=md5:a0bab457cbf5b4f8eb99d1d0a3ada420 # Sets md5 hash or pgp/gpg sig url
+ WEB_SITE=http://www.gnu.org/software/emacs # where to learn more
+ ENTERED=20010922 # First appearance in moonbase
+ UPDATED=20020529 # Date of latest change.
+ # Force update by setting this
+ # The remaining lines are used for input to the 'lvu what' command
+ # and are best copied from the source-maintainer's own description.
+ SHORT="Emacs is the extensible, self-documenting real-time display editor."
+cat << EOF
+Emacs is the extensible, customizable, self-documenting real-time display editor.
+EOF
+\end{lstlisting}
+
+\subsubsection{The DEPENDS script}
+
+The \lstinline{DEPENDS} script is essential to configuration management, and is the key to the overall operation of lunar. Dependencies should be exactly specified, preferably not assuming the presence of any other modules, while knowing the sub-dependencies of the modules which are added and not adding those explictly where not needed. \par
+
+\textbf{Warning}: Getting this right is difficult. Because the state of installed packages may vary widely, it's important to have a good understanding of what might be or not be installed on a target system. \par
+
+\textbf{Note} By convention Lunar does not include the X Window System (xfree86) in any dependency. There are two reasons for this choice. First we expect that users must understand that to use a graphical application locally, the X Window System must be installed. Second, due to the sligtly unusual definition of client and server used by X11, it is often in fact possible to build graphical applications and tools for remote display, without the server components locally installed. At some future date we may elect to provide a client-only installation of xfree86. \par
+
+\lstinline{DEPENDS} may include both required and optional dependencies. The depends() function statement simply determines one required package. The \lstinline{optional_depends} function is a little more complex. It consists of the required package, necessary --options to give to\lstinline{ ./configure} (for yes and no respectively, and an explanatory comment telling the user the purpose of the option being presented. A typical \lstinline{DEPENDS} file might appear as follows : (\lstinline{/var/lib/lunar/moonbase/devel/subversion/DEPENDS})
+
+
+\begin{lstlisting}
+depends zlib &&
+depends openssl &&
+optional_depends "db4" "--with-berkeley-db" "" "for creating local repositories"
+# ^ ^ ^ ^
+# | | | |
+# optional package if "Y" if "N" explanatory comment
+# { ./configure strings }
+\end{lstlisting}
+
+\subsubsection{The \lstinline{CONFLICTS} script}
+
+This script is simply used to specify modules which will be removed when a given module is installed. An example would be : (\lstinline{/var/lib/lunar/moonbase/editors/elvis/CONFLICTS})
+
+\begin{lstlisting}
+conflicts vim
+\end{lstlisting}
+
+\subsubsection{The \lstinline{CONFIGURE} script}
+
+The \lstinline{CONFIGURE} script is used to collect interactive input from the user on optional parameters for the software build. use the \lstinline'query' function and provide a default answer to each question. The results of the answers are then used to store configuration variables needed in configuration state files. An a simple example might be : (\lstinline{/var/lib/lunar/moonbase/crypto/gnupg/CONFIGURE})
+
+\begin{lstlisting}
+if ! grep -q CONFIGURED $MODULE_CONFIG ; then
+ if query "Enable experimental external HKP keyserver interface? " n ; then
+ OPTS="$OPTS --enable-external-hkp"
+ fi
+
+ echo 'CONFIGURED="y"' >> $MODULE_CONFIG
+fi
+\end{lstlisting}
+
+\subsubsection{The PRE\_BUILD script}
+
+\lstinline{PRE_BUILD} is used where special processing is needed before undertaking the actual build steps. Typical requirements include unpacking multiple sources, creating necessary system or source-tree direcotries and applying source patches. And example would be : (\lstinline{/var/lib/lunar/moonbase/doc-tools/html2db/PRE_BUILD})
+
+\begin{lstlisting}
+mk_source_dir $SOURCE_DIRECTORY &&
+unpack $SOURCE &&
+cd $MODULE
+unpack $SOURCE2
+cd tidy
+patch_it $SOURCE_CACHE/$SOURCE3 0
+cd /usr/src/$MODULE
+\end{lstlisting}
+
+\subsubsection{The BUILD script}
+
+\lstinline{BUILD} is used where the \lstinline{default\_build()} function does not work for a given software package. For reference the commands run by default are: \\
+
+Function \lstinline{default\_build()} calls \lstinline{default\_config} which executes:
+
+\begin{lstlisting}
+ ./configure --build=$BUILD \
+ --prefix=/usr \
+ --sysconfdir=/etc \
+ --localstatedir=/var \
+ --infodir=/usr/share/info \
+ --mandir=/usr/share/man \
+ $OPTS
+\end{lstlisting}
+
+Next, \lstinline{default\_build()}: calls \lstinline{default\_make} which executes:
+
+\begin{lstlisting}
+ make &&
+ make install
+\end{lstlisting}
+
+Where this build configuration does not work, the \lstinline{BUILD} script is used to provide the needed steps. about 75\% of modules need a \lstinline{BUILD} script. Two examples include : (\lstinline{/var/lib/lunar/moonbase/archive/gzip/BUILD})
+
+\begin{lstlisting}
+(
+
+./configure --build=$BUILD \
+ --prefix=/usr \
+ --bindir=/bin \
+ --infodir=/usr/share/info \
+ --mandir=/usr/share/man &&
+make &&
+prepare_install &&
+make bindir=/bin install
+
+) > $C_FIFO 2>&1
+\end{lstlisting}
+
+and : (\lstinline{/var/lib/lunar/moonbase/editors/ex/BUILD})
+
+\begin{lstlisting}
+(
+ cd $SOURCE_DIRECTORY &&
+ sedit 's/usr.local/usr/' Makefile &&
+ sedit 's/= man/= share/man/' Makefile &&
+ sedit 's/ucb/bin/' Makefile &&
+ sedit 's/= termlib/= ncurses/' Makefile &&
+ make &&
+ prepare_install &&
+ make install
+
+) > $C_FIFO 2\&1
+\end{lstlisting}
+
+The first example is a build which needs non-standard \lstinline'configure' and \lstinline'make install' commands. The second is a build which does not use gnu auto-tools' \lstinline'configure' script. \par
+\textbf{Note} \lstinline{BUILD} scripts must execute inside a () (subshell invocation) construct and output is always directed to a named pipe (aka FIFO). Therefor all \lstinline{BUILD} files take the follwing form:
+
+\begin{lstlisting}
+(
+ command(s)
+) > \$C_FIFO 2>&1 # $
+\end{lstlisting}
+
+\lstinline{C_FIFO} holds the name of a fifo in \lstinline{/tmp} used for \lstinline'voyeur'
+
+
+\subsubsection{The POST\_BUILD script}
+
+\lstinline{POST_BUILD} runs in place of the \lstinline{default_post_build} routine which is used to install minor documentation and transfer/enable initialization scripts and similar system data, mostly into /etc. An example script would be : (\lstinline{/var/lib/lunar/moonbase/net/samba/POST_BUILD})
+
+\begin{lstlisting}
+if [ ! -d /etc/samba/private ]; then
+ mkdir -p /etc/samba/private
+ chmod 700 /etc/samba/private
+fi
+\end{lstlisting}
+
+\subsubsection{The POST\_INSTALL script}
+
+\lstinline{POST\_INSTALL} has no equivalent functions, and is run to handle post-installation work in a general manner. An example is : (\lstinline{/var/lib/lunar/moonbase/compilers/gcc/POST_INSTALL})
+
+\begin{lstlisting}
+cd /usr/lib/gcc-lib/$BUILD/$VERSION &&
+ln -sf /usr/bin/cpp cpp &&
+cd /lib/ &&
+ln -sf /usr/bin/cpp cpp &&
+
+if [ ! -e /usr/bin/cc ] ; then
+ ln -s gcc /usr/bin/cc
+fi &&
+
+rm_source_dir /usr/src/gcc-$VERSION-BUILD &&
+rm_source_dir /usr/src/gcc-$VERSION &&
+
+ldconfig
+\end{lstlisting}
+
+\subsection{Package Removal Scripts}
+
+Module removal is handled by \lstinline!lrm(8)!. Because installation is monitored (and backup tarballs are created using) installwatch, most of package removal is handled automatically using the logs created by installwatch. However we provide for additional actions to be taken through the \lstinline{PRE_REMOVE} and \lstinline{POST_REMOVE} scripts. \par
+
+\subsubsection{The PRE\_REMOVE script}
+
+\lstinline{PRE_REMOVE } is needed to execute any tasks needed prior to the main task of removing all files installed by the module. An example would be : (\lstinline{/var/lib/lunar/moonbase/mail/courier-imap/PRE_REMOVE})
+
+\begin{lstlisting}
+if [ -x /etc/init.d/imapd ]; then
+ /etc/init.d/imapd stop
+fi
+
+chkconfig --del imapd
+\end{lstlisting}
+
+\subsubsection{The POST\_REMOVE Script}
+
+\lstinline{POST_REMOVE} may be used to remove data not tracked by installwatch and to correctly adjust remaining configuration files and data. Examples would include \\ (\lstinline{/var/lib/lunar/moonbase/devel/binutils/POST_REMOVE}) :
+
+\begin{lstlisting}
+install-info --delete as --info-dir /usr/info
+install-info --delete bfd --info-dir /usr/info
+install-info --delete binutils --info-dir /usr/info
+install-info --delete configure --info-dir /usr/info
+install-info --delete gasp --info-dir /usr/info
+install-info --delete gprof --info-dir /usr/info
+install-info --delete ld --info-dir /usr/info
+\end{lstlisting}
+
+or : (\lstinline{/var/lib/lunar/moonbase/compilers/php/POST_REMOVE})
+
+\begin{lstlisting}
+if module\_installed apache; then
+
+ cp /etc/httpd/httpd.conf /tmp/httpd.conf
+ grep -v "LoadModule php4_module" /tmp/httpd.conf |
+ grep -v "AddModule mod_php4.c" > /etc/httpd/httpd.conf
+ rm -f /tmp/httpd.conf
+ /usr/sbin/apachectl graceful
+
+
+elif module_installed apache_mod_ssl; then
+
+ cp /etc/httpsd/httpd.conf /tmp/httpd.conf
+ grep -v "LoadModule php4_module" /tmp/httpd.conf |
+ grep -v "AddModule mod_php4.c" > /etc/httpsd/httpd.conf
+ rm -f /tmp/httpd.conf
+ /etc/init.d/apache_modssl.sh restart
+
+fi
+\end{lstlisting}
+\subsection{Versioned scripts}
+
+To provide support for multiple simultaneous versions of a given package, (and to eas migration between versions) lunar supports a module/version syntax.
+Designing versioned scripts \par
+
+\textbf{Note}: Versioning is not a panacea, while certain problems can be solved by using versioning, it is important both to understand how versions are implemented in lunar as well as the specific implications for a given package of the presence of multiple versions of specific libraries and executables. \par
+
+Alternate versions of modules are created by adding a version subdirectory under the module's main directory. For example the gcc directory contains the subdirectories for gcc versions 3.3 and 3.3.1; gcc/3.3.1 contains all of the same files needed to build the default version (3.2.3 at the time of this writing). \par
+
+\begin{lstlisting}
+thing:/lp/moonbase/compilers/gcc$ ls -lr
+total 26
+-rwxr-xr-x 1 elaine users 254 Dec 3 2002 PRE_BUILD
+-rwxr-xr-x 1 elaine users 228 Aug 20 2002 POST_REMOVE
+-rwxr-xr-x 1 elaine users 490 Oct 17 2002 POST_INSTALL
+-rwxr-xr-x 1 elaine users 966 Apr 25 16:54 DETAILS
+-rwxr-xr-x 1 elaine users 1119 Feb 1 2003 CONFIGURE
+-rwxr-xr-x 1 elaine users 1123 Apr 25 16:54 BUILD
+drwxr-xr-x 3 elaine users 248 Sep 12 09:18 3.3.1
+drwxr-xr-x 3 elaine users 248 Sep 12 09:18 3.3
+
+thing:/lp/moonbase/compilers/gcc$ ls -lr 3.3.1
+total 25
+-rwxr-xr-x 1 elaine users 254 Sep 7 18:09 PRE_BUILD
+-rwxr-xr-x 1 elaine users 228 Sep 7 18:09 POST_REMOVE
+-rwxr-xr-x 1 elaine users 582 Sep 7 18:09 POST_INSTALL
+-rwxr-xr-x 1 elaine users 956 Sep 7 18:09 DETAILS
+-rwxr-xr-x 1 elaine users 1119 Sep 7 18:09 CONFIGURE
+-rwxr-xr-x 1 elaine users 1211 Sep 7 18:09 BUILD
+\end{lstlisting}
+
+\subsection{Module/version requirements}
+
+\begin{itemize}
+\item Naming rules: module/version
+ \subitem required: Alternate version modules must have same \lstinline{MODULE} name
+ \subitem required: Directory and variable \lstinline{VERSION = "[0-9]*"} (must begin with an integer)
+ \subitem preferred: Use shortest reasonable /version string (e.g. 0.9.5, 0.9.5-test)
+\item Installation requirements
+ \subitem preferred: Alternate version modules install in \lstinline{/opt/lunar/module/v.v} or similar location
+ \subitem required: Data objects which functionally differ between versions must not conflict/overwrite
+ \subitem allowed: functionally identical supporting data (e.g. /usr/share/doc/module) may overwrite if this is deemed safe in a given instance
+\item \lstinline{DETAILS} script
+ \subitem The \lstinline{MODULE=} variable must be changed to module/version syntax. Example:
+ \lstinline{MODULE=gcc/3.3.1}
+ \subitem \lstinline{$MODULE} and \lstinline!${MODULE}! references are disallowed in \lstinline{/v.v/DETAILS} files
+ \subitem Works: \lstinline{SOURCE=gcc-$VERSION.tar.bz2}
+ \subitem Breaks: \lstinline!SOURCE=${MODULE}-$VERSION.tar.bz2!
+\item \lstinline{BUILD} script : May need no more changes than adjusting ./configure --options. Example: \lstinline{./configure --prefix=/opt/lunar/gcc/3.3.1 \}
+
+\item \lstinline{DEPENDS} script: In complex systems (e.g. desktops) many dependencies may need to be converted to module/v.v form.
+\end{itemize}
+
+\subsection{Discussion: Why versioned modules}
+
+Many key applications install themselves with full version information, perl, emacs and gcc would all be good examples. They build private arch-version specific libraries allowing multiple versions to be simultaneously installed. \par
+
+Unfortunately it's not, or at least not always simple. Many software builds now seem to install a mix of libraries which may be accessible thru ldconfig and private libraries known by their install paths, and it's not always clear which is which (and some sometimes seem to be both). \par
+
+Outline of the steps needed to get gnome2/2.4.0 working.
+
+\begin{enumerate}
+\item \textbf{Backup} of /opt/lunar/gnome/2 so that I could roll-back to prior state and test bugs in the build.
+ \item Development of a perl script to roll back \lstinline{/var/state/lunar/packages*} files to match the prior-state gnome(2.2). --- necessary because mismatched versions in the packages files cause script breakage.
+\item Isolation of the packages which needed to be rewritten in /version notation. I started with the list which Nick provided for gnome 2.4 build and added a few more which were pulled in as dependencies and caused breakage if not /versioned. \textbf{NOTE} this step is predictably imperfect, my gnome configuration was only what had been installed by \lstinline'lin gnome2' when it was version 2.2, with not much optional deps selected. different optional deps and/or added gnome 'stuff' will probably add some things to this list.
+\item Moving some things out of \lstinline{/usr}, into \lstinline{/opt}. About 3 of the gnome2 modules used \lstinline{./configure --prefix=/usr}. Nick indicated that this had been neccessary only because the first time through he'd been unable to get them working in \lstinline{/opt}.
+ \item Fixing dependencies. Given the list from step 3 I used a shell cmd:
+
+\begin{lstlisting}
+for i in `cat /root/all`; do
+ echo -n "s:($i)[ \t]:\ $1/";
+ echo -n `basename */$i/[0-9]*`;
+ echo " :;" ;
+done > ~/edit.pl
+\end{lstlisting}
+
+ Making the following perl:
+
+\begin{lstlisting}
+s:(linc)[ \t]:$1/1.1.1 :;
+s:(libIDL)[ \t]:$1/0.8.2 :;
+s:(ORBit2)[ \t]:$1/2.8.1 :;
+s:(libbonobo)[ \t]:$1/2.4.0 :;
+s:(GConf2)[ \t]:$1/2.4.0.1 :;
+...
+\end{lstlisting}
+
+\item Once all that was done (several iterations of 1,2 a couple of 3-5) a clean build.
+\end{enumerate}
+
+\subsection{Caveats}
+
+Please remember versioning has 2 (main) intentions:
+
+\begin{enumerate}
+\item Allowing relatively long-term coexistence of (mostly) programming tool versions.
+\item Enabling more orderly transition (and perhaps safer rollback) between versions of the more complex and error-prone modules.
+\end{enumerate}
+
+It's assumed that to switch between versions (at either runtime or buildtime) the user may need to a. modify the PATH (not *always necessary, e.g. \textbf{most, not all } applications will build correctly by setting \lstinline{CC=/path/to/my/C/compiler}.) \par
+
+Additionally assume the user may need to either set \lstinline{LD_LIBRARY_PATH} or edit \lstinline{/etc/ld.so.conf} and run \lstinline'ldconfig' which is more invasive and (for now) requires root privilege. \par
Modified: lunar-doc/trunk/lunar-manual/Lunar_Book.tex
===================================================================
--- lunar-doc/trunk/lunar-manual/Lunar_Book.tex 2005-07-06 17:27:25 UTC (rev 15617)
+++ lunar-doc/trunk/lunar-manual/Lunar_Book.tex 2005-07-07 00:56:56 UTC (rev 15618)
@@ -5,8 +5,11 @@
\usepackage[pdftex]{graphicx}
\usepackage{array}
\usepackage{floatflt}
+%we use floatflt package for floating text around images, which is really nice, but can be tricky. not used by now (7.05) but nobody knows the future
+\usepackage{listings}
+%We use the listings package for displaying code, as we get lots of compile errors else, and it looks just fantastico !
+%for commands, keys to be pressed etc. we use \textit
-
\textwidth 15cm
\textheight 23cm
\oddsidemargin 0cm
@@ -16,6 +19,8 @@
\topmargin 0cm
\selectfont
\sf\sffamily
+\lstset{language=bash, numbers=left, numberstyle=\tiny, stepnumber=2, numbersep=5pt}
+%numbers at left side of source code, small, every 3 steps display on, 5pt away from code
\begin{document}
@@ -45,22 +50,22 @@
\newpage
-\include{chapter1}
+\include{1installation}
-\include{chapter2}
+\include{2using_lunar}
-\include{chapter3}
+\include{3troubleshooting}
-\include{chapter4}
+\include{4inside_lunar}
-\include{chapter5}
+\include{5getting_to_work}
-\include{chapter6}
+\include{6development}
\include{appendices}
More information about the Lunar-commits
mailing list