My FREESCO page | Compiling for FREESCO
Note! Unfortunately I do not have time to keep this page updated. Please consult the FREESCO forums if you need more information about compiling stuff for FREESCO.
After using FREESCO for a while, you might be interested in developing/compiling applications for it. Basically, this is quite an easy task as all it takes is to download and install Zipslack and then you are ready to go. However, if you are a Linux newbie this might seem complicated and tedious. Hopefully, this document will help you get going! It describes how to set up a development environment that can be used to compile and package applications for FREESCO.
This document is based on information compiled from several sources. The basic information on how to compile stuff for FREESCO was written by Lee Dowling "Ledow". Without his documentation I would never had been able to produce this document. Dingetje has Ledow's documenation mirrored on his site and this is where I found it. Of course, the FREESCO support forums http://forums.freesco.org/ has been an invaluable information source when putting together this document.
I am a Linux noob and by no means an expert on this. I bet there are thousands of things that can be done in other ways. I do not claim that this is the "only" or the "correct" way to set up this environment; this is simply a description of how I did it. If you have any comments on the document, please don't hesitate to contact me:
[ Top ]
The purpose of this document is to describe how to set up a Zipslack machine and use it for compiling applications for FREESCO. The document is written for Linux newbies to help them get going. Zipslack is not the only possible distro to use. Older, libc5 based Red Hat should also work, but I believe Zipslack is most commonly used and hence focused here.
[ Top ]
This document is focused on how to set up the development environment; it DOES NOT teach you to program. You must know how to compile applications in a Linux/UNIX environment (using make) to benefit from the instructions. You should also know basic Linux commands such as
[ Top ]
I will describe how to set up a separate machine on your local network and use it for compiling applications. The machine will be running Zipslack 3.9 with a simple window manager. It will be possible to access the machine remote (using telnet or VNC), so the machine will be accessible from another machine within the LAN. This gives you the opportunity to set up a machine for compiling and put it away under a desk or in a wardrobe.
The picture below shows my home network. I have a FREESCO and a switch and behind that my LAN. I have two PC:s and the Zipslack machine. I can operate the Zipslack either from its keyboard or from any of the other computers on the net. By following the instructions in this document, you'll end up with something similar.
[ Top ]
In order to setup the Zipslack, the following is needed:
[ Top ]
The machine that should be used for Zipslack must have at least one partition of the hard disk formatted using FAT. If you have Windows 95/98/ME installed you are safe, these OS:es uses this file system. If you run any of these OS:es together with NT/W2K/XP (this is what I do), you are also safe. However, if you only use NT, W2K or XP you have a problem. These operating systems (normally) use another file system called NTFS from which Zipslack won't run. From what I've heard it is quite complicated to add W95/98/ME to a machine that already runs NT/W2K/XP (It is doable, at least for XP. Just Google on "install+windows+98+after+xp" and you will come up with some pages on this topic). An alternative to this approach is to get yourself a separate computer that you can install any of the FAT OS:es on. If you can afford another computer I would recommend this approach.
Milestone 1: You should have a FAT-based computer which you can boot into Windows 95/98/ME. For the rest of this tutorial I assume it runs Windows 98, but W95 or ME will also do.
Zipslack runs from DOS. To get into DOS on your W95/98/ME machine, you usually have to keep pressing F8 or CTRL when booting. Personally I got tired of this and found out that it is possible to configure W98 to always show the boot menu. This menu gives the user a choice whether to start in Windows or DOS. There are several ways to configure this: in the registry, using PowerToys or by editing MSDOS.SYS. I recommend editing MSDOS.SYS as this approach gives you more control. A good site for references on how to edit this file is http://www.mdgx.com/msdos.htm. The file contains several sections and the one to edit is the [Options] section. This is how my file looks:
[Options] ;Show boot menu BootMenu=1 ;Enable the boot keys (F4, F5, etc) BootKeys=1 ;What to start by default. On my machine option 5 means DOS ;so I use this as the default option BootMenuDefault=5 ;Delay before default choice is started BootMenuDelay=5 ;Don't touch the rest BootMulti=1 BootGUI=1 DoubleBuffer=1 ... ...
With this setup, the boot menu is always shown. It waits 5s before choice number 5 (which is DOS) is started, which gives me enough time to hit the correct key to boot Win98 when I want. To apply these changes, do the following:
Milestone 2: You should now be able to boot your machine into DOS (as well as Windows) using the boot menu.
[ Top ]
Zipslack is a stripped version of a complete Linux distribution called Slackware. Anything that runs on the full distro is also expected to run on Zipslack (assuming the same version is used) so it is possible to set up quite a competent Linux based on Zipslack.
Zipslack is found on Slackware's site, http://www.slackware.com/zipslack/. There are several versions available and what you should look for is 3.9, available from ftp://ftp.slackware.com/pub/slackware/slackware-3.9/zipslack/zipslack.zip (38,161,662 bytes).
Installing Zipslack is quite easy:
linuxin the root of the drive
linux.bat. This file is used for starting Zipslack. Start Notepad and load the file into the editor.
rem \linux\loadlin \linux\vmlinuz root=/dev/xxxN rw
remwhich means that the row is commented out and not active. By default the first row is active. This row specifies that the kernel is located on a SCSI zipdrive. However, this is not where most of us have the kernel. Instead, the most common place to find the kernel is on the first partition on IDE disk A (dev/hda1). Hence we must edit the file. Start by comment out the default choice by changing
\linux\loadlin \linux\vmlinuz root=/dev/sda4 rw
rem \linux\loadlin \linux\vmlinuz root=/dev/sda4 rw
rem \linux\loadlin \linux\vmlinuz root=/dev/hda1 rw
\linux\loadlin \linux\vmlinuz root=/dev/hda1 rw
linux.batfile from its original location (C:\linux\) to the root of C:\
Well, that's about everything! Now shut down the machine and boot to DOS. Once you are in DOS, just type
and Zipslack should start. Login with user name "
root" (without "":s and in lowercase) and just press return to skip the password. Tada - you are logged in to your new Zipslack machine! Once you are logged in, you can shutdown Zipslack by giving the command "
Milestone 3: You should now be able to boot into Zipslack.
[ Top ]
By default, Zipslack 3.9 uses kernel 2.0.37 (this is displayed at the prompt, just before you log in). There are newer versions of the kernel available and it is recommended to update the kernel. Newer versions of FREESCO use kernel 2.0.40 or 2.0.39. There were some problems reported with the 2.0.40 kernel and the upcoming version of FREESCO (0.3.4) will be based on 2.0.39. Updating the kernel of your Zipslack to the same version is hence a good idea.
First you must get the kernel sources. Start your machine in Windows and download the kernel source. You probably want to get the FREESCO kernel source (the vanilla kernel will probably not work very well). Store the file in the Zipslack base directory (C:\Linux\). Now shutdown Windows and boot Zipslack.
During bootup, the downloaded kernel will be renamed to a 8+3 file name. The first thing to do is to rename it back to its original name which is done with
cd / mv linux-* linux-2.0.39.tar.gz
Once the kernel source is named correctly, it should be moved to the correct position. This is done with
mv linux-2.0.39.tar.gz /usr/src cd /usr/src
Now it is time to extract the sources:
tar -xvzf linux-2.0.39.tar.gz
Lots of filenames will scroll by on the screen. If it finishes with an error message, chances are you ran out of free disk space. Now we have the correct source code in place and just need to configure and make the kernel. The source is located in a sub-directory called
/usr/src/linux) and in order to build the kernel we enter this directory:
[ Top ]
Before the new kernel can be compiled, you have to configure it. In this process you tell which features that should be included in the kernel and which features that should be left out. For more information about configuration, see the README file located in
/usr/src/linux. There is also a directory called
Documentation that contain other valuable documents.
Configuring the kernel is complex and you might end up with a result where your Zipslack doesn't start. Hence I will describe how to get a decent kernel. If you look for performance and want to tune your kernel there are several things to improve. However, the purpose here is to get a decent kernel that works under most circumstances. Before you continue with this step you should find out the name/type of your NIC, otherwise the kernel can't be configured correctly (it is possible to add a module for your NIC later on, but if you have this information now you don't have to care about it later). When you have identified your NIC you can start the configuration with
A simple GUI is displayed after a while and this is where you configure the kernel. The GUI contains a menu with several choices. Only the following has to be changed:
Loadable module support: Enter this menu and select the option "Kernel daemon support (e.g. autoload of modules)" by pressing "Y".
General setup: In this menu, select the sub menu "(Pentium) Processor Type" and change this to what best matches your CPU. I use PPro for my 566 Celeron
Floppy, IDE, and other block devices: Scroll down to the section that starts with "--- Additional Block Devices" and press "Y" when "Loopback device support" is selected. This option is not necessary, but it makes it possible to mount a disk file as a file system. If you ever want to rebuild the ram disk, you need this.
Network device support: Here you should lookup the vendor/name of your NIC. I have a Realtek 8139 which is "hidden" under the choice "PCI Ethernet Adapters". You must first enable this sub menu, then a list of actual NICs will be displayed. You now have the choice to either compile support for the NIC into the kernel or compile a module for it. The later is a bit more complicated but gives you a smaller kernel. As size is not a big issue here, I recommend compiling support into the kernel, so enter a "Y" in front of your NIC type.
Filesystems: Your kernel must support UMSDOS so enter a "Y" in front of this choice.
Now you are finished so you can exit the configuration application. Answer 'Yes' when you are asked whether to save the configuration or your settings will be lost! When you are back at the prompt it is time to build the kernel. This is done with
make dep make clean make zImage make modules make modules_install
Note: If you run out of memory when compiling the kernel, you might need to enable a swapfile. A 256MB swapfile can be created with:
dd if=/dev/zero of=/myswap bs=1M count=256 mkswap myswap swapon myswap
Update: It has been reported that the above does not work. The syntax of the
dd command is wrong as
dd does not seem to understand the 'M'. Instead of
bs=1048576 has been used successfully.
When this is done, you have compiled your new kernel, all modules and also installed the modules. Now it is time to move the new kernel so it is used in next boot. First we must get rid of the old kernel. Instead of deleting it (it might be good to have if you mess up your system), we just rename it:
cp /vmlinuz /vmlinuz_org
Now we can overwrite the original kernel with our new one:
mv ./arch/i386/boot/zImage /vmlinuz
This is it! Your new kernel is in place and you can reboot your system. The next time your system start, you should be logging in to a 2.0.39 system. You can tell that the kernel is updated when you see
"Welcome to Linux 2.0.39"
on the screen.
Milestone 4: You should now have patched the kernel of your Zipslack.
Note: If you want to compile your own kernel or a kernel module, you should use the FREESCO kernel source instead of the source from kernel.org. This source is available from http://freesco.sourceforge.net. Snippet from the forums:
Isn't it advisable to download the Freesco kernel source (because it's patched a bit) instead of the kernel at kernel.org?
REQUIRED would be closer than "advisable". The reason is that there are actually a LOT of changes to the FREESCO kernel and of those changes quite a percentage of patching was done manually because of conflicting code and versions with specific patches that are not availible for the exact version of kernel. You also get the default configuration for the stock kernel and you only have to add the new changes that you want.
Just go to sourceforge and the new kernel source is availible for download.
But of course if you are just talking about getting Zipslack to run on your laptop and you have absolutely no plans on ever making a FREESCO kernel. Then ANY Linux 2.0.39 kernel will do.
[ Top ]
Your Zipslack is now ready and it is running your new kernel. There are however some additional tweaks left before we are done: getting the network to run and make it possible to use VNC to control the machine.
The first thing to do is to get your Zipslack up on your network. To do this, run
to start the network configuration utility. Configuration is pretty straightforward. The IP of the Zipslack is set to a static value so be sure to set it to a value within the range of your router. Once you are done, reboot or run
Verify you have access to the network.
Milestone 5: You should have access to internet from your Zipslack
As we will access the Zipslack remote, there are some things to adjust. These adjustments are only necessary if you plan to use the Zipslack as root. Using the machine as root is a security risk and is generally not recommended. However, I believe this is a special situation where security is not a big issue. The machine is a development machine located within your own network. If you have full control of your network I don't think there's much to worry about. If you want, you are free to create an extra user on your Zipslack and use it instead of root. As I use the root account I have to do the following adjustments.
First the password of the root user should be changed (or rather, set) with
Then we must allow root to telnet to the machine (yes, telnet is generally insecure and bad, but once again, security is not a big issue here). To achieve this we must edit
/etc/securetty. The easiest way (in my oppinion) is to use
mcedit. Open the file with
Once the file is opened in the editor, uncomment the lines
#ttyp0 #ttyp1 #ttyp2
so they read
ttyp0 ttyp1 ttyp2
Save the changes and exit the editor. We should also allow root to ftp to the Zipslack (handy when moving files to the machine). Open
/etc/ftpusers in the editor and comment out the line with
so it reads
Save changes and exit the editor. Once again reboot your system (or use
Milestone 6: You should be able to telnet and ftp to your Zipslack as root from any machine on your LAN.
[ Top ]
At this stage you have a complete development machine. You can log in to it remote and do whatever you want. As an additional step you can add a simple graphical environment which (at least in my book) makes life a bit easier. This can be done by using VNC and its build in X-server Xvnc. I found it quite easy to set it up and I really enjoy it. As mentioned, this step is optional so if you are satisfied with the shell, you can stop reading here. If you are unfamiliar with VNC, take a look at http://www.realvnc.com
[ Top ]
If you go to the VNC site you will find several versions available. You can download pre-compiled versions as well as source code. Unfortunately, I didn't get the pre-compiled versions to work on my Zipslack. It looks like it needs a lib that is unavailable for Zipslack 3.9 (libstdc++- something). However, I managed to compile the old version (3.3.7) without any fuzz and it works very well. The reason I didn't try the 4.1 or 4.0 version was the statement in the VNC README which said it was much more complicated to build Xvnc in these versions. As 3.3.7 worked well, I didn't see any reason to put any energy in getting a later version working too. So this is a description on how to build VNC 3.3.7 for Zipslack 3.9.
Boot your machine in Windows, go to the VNC site and enter the "Download" section. Look for the free version of the older 3.3.7. After entering some information you are redirected to the download section where you find the sources (vnc-3.3.7-unixsrc.tar.gz). Download the file and save it somewhere in the Zipslack directory structure (c:\linux)
Shutdown Windows and boot Zipslack. The VNC sources will be renamed during boot so we must rename it back to its original name. At the same time we move the file to the home of root:
cd / mv vnc-* /root/vnc-3.3.7-unixsrc.tar.gz cd /root
[ Top ]
In order to compile Xvnc we need to extend our Zipslack with some parts of X. These parts (aka packages) can be found on the Slackware ftp site (ftp.slackware.com). On your Zipslack, use ncftp to download the files below. They are all found in directory
xbin.tgz xprog.tgz xlib.tgz xfnts.tgz
Tip: If you use
ncftp to transfer the files, you can use the command
mget xbin.tgz xprog.tgz xlib.tgz xfnts.tgz
to get all files at once. When you have the packages downloaded, it is time to install them. This is done with the command
installpkg together with the package name, ie
If you have all packages in the same directory (and no other *.tgz files there), you can run
to install all packages at once. After installing the libraries we need to update the system with the new libs. This is done with
Your system is now ready for building VNC and Xvnc.
[ Top ]
Now it is time to unpack the VNC sources:
tar -xvzf vnc-3.3.7-unixsrc.tar.gz
Files are unpackaged to a directory named vnc-3.3.7-unixsrc. Enter it and run configure to prepare the make files:
cd vnc-3.3.7-unixsrc ./confiugre
When this has finished we are ready do build VNC:
Finally, we should make Xvnc. Enter the Xvnc directory and build:
cd Xvnc make World
This takes quite a while so have patience. While you wait for the compilation to finish you can download and install a VNC viewer on the machine that you will use when connecting to your Zipslack.
When compilation of Xvnc has finished it is time to install VNC. Go back up to the VNC main directory and install VNC to a directory that is in your PATH, for example
cd .. ./vncinstall /usr/local/bin
When finished, it is possible to start Xvnc with the command
By default it will use display 1, but that can be specified when starting the server. Eg:
will use display 3. The first time you start the server you will be asked for a password. This password is used when connecting a viewer to the server. Once the server is started, you can attach a viewer to it. The viewer is run on the machine you use to access the Zipslack remote. Start the viewer and enter the IP of your Zipslack followed by the display number, eg:
will try to connect a viewer to display 3. If everything goes well you should end up with a simple X display and a xterm window.
If you want vncserver to run automatically each time you boot your Zipslack, enter the following in
su - root -c 'source /etc/profile ; vncserver'
Note: I discovered that it was not possible to use Alt-Tab on my XP box to cycle to another window when the VNC viewer was active. In order to get this working you must configure the VNC viewer. When you start the viewer, press the "Options..." button in the dialog where you enter the IP of the machine to connect to. Now select the "Inputs" tab and uncheck "Pass special keys directly to server". Then press the "Load/Save" tab and save these settings as default. Now Alt-Tab should be working again.
Milestone 7: You should be able to start a VNC server on your Zipslack and connect a viewer to it from any computer within your LAN.
[ Top ]
Now your Zipslack is up and running and you are ready to start use it. Before you begin you might want to install some additional packages. Below I list some packages I find absolutely necessary:
You can browse all the available packages on ftp.slackware.com/pub/slackware/slackware-3.9/slakware/. If you are looking for a certain package you can use the Slackware Package Browser. It makes it possible to search for packages/files using package name, file name or file description. The browser supports Slackware from version 8.1 but it is still helpful for older versions of Slackware as it can hint you were to find a certain package.
[ Top ]
This is not a tutorial on how to compile applications on a Linux box, you are supposed to know this already. However, in short the process is:
./configureto create the makefiles
maketo build the application
Once you have the binaries compiled it is time to package them for FREESCO. Unless you REALLY know what you are doing, you are supposed to use Lightning's excellent Packager. This is a *.tgz archive with some scripts that you can use to create your package with. The archive contains a REAME file which describes how to use it. The archive is available from FREESCOsoft but sometimes Lightning post updates that takes a while to get to FREESCOsoft, so searching the forums usually finds the latest version available. Use the keyword "packager" and search for posts by "Lightning".
One thread that might be of interest is this which describes file locations and how to use the Packager. This thread describes the package directory structure of the 03x series.
[ Top ]
This is the most important phase of the development/packaging process: to test and verify your package. You probably don't want to use your "real" FREESCO for this as it might make it unstable and mess it up with packages still in development. Personally I use Bochs when testing packages and it works very well. Bochs is an emulator that makes it possible to emulate and run any OS on your PC. For each system that should be emulated there is a configuration file (*.bxrc) and one or several disk images (*.img).
[ Top ]
Tom has made a set of files that can be used to setup and emulate different versions of FREESCO. This is the latest release of the necessary files together with a description of how to use them. Here you find a more detailed thread which includes solutions to some setup problems. These threads contain information about how to install and set up the Bochs environment. To summarize, the process is:
cdto the directory where you downloaded it.
windump -Dwhich will give information about your NICs:
That should be it. You should now be able to run the emulator by double clicking the *.bxrc file.
I had some problems getting FREESCO emulation to work. My machine simply booted to fast and the FREESCO ended up without an IP. I got the following responses from Tom in the forums:
"If you get kernel errors then you have to adjust the 'ips' setting in the bochsrc.bxrc file to match your real CPU"
"Try adjusting your "ips=" setting, it took a little tweaking to find the right number for me. On my Athlon xp 2100+, 2000000 works just right. I did notice that FREESCO is pretty picky about this setting and I had similar problems with FREESCO saying "Failed/Delayed" when it was trying to get its IP (when it was booting too fast). Try slowing it down a little bit and see if that works.
Also, if you ever experience kernel crashes (on FREESCO or ZipSlack) then the ips setting is definitely the problem and needs to be fine-tuned"
You might also need to reconfigure the NIC settings in FREESCO (advanced settings 53). Base address and IRQ in the FREESCO setup should match what you specify in the configuration file. By default, these are set to a value matching Tom's system.
One final note, I had problems getting Bochs running the emulation correctly when installed on D:. I don't know if this is just my machine or something general. When running from C: I had no problems.
Milestone 8: You should now be able to run and emulate any of the systems included in Tom's FREESCO package.
[ Top ]
Once you have Bochs installed you can start use it. When developing and testing packages, I use Bochs together with Tom's packages in the following way (I use FREESCO 032 files as example):
Thanks to Bochs (and Tom!) it is extremely easy to test your package on a new FREESCO.
The Bochs-packages created by Tom also contains a complete Zipslack environment. This means that there is no need to setup a separate Zipslack machine in order to compile stuff for FREESCO. This can all be done by using Bochs! I tried this and it works well. However, my machine is too slow to compile stuff with descent speed, hence I decided to not use this approach. But if you have a fast machine this might be a good alternative to setting up a Zipslack (although not half as fun!).
[ Top ]
By now you should have a Zipslack that is able to compile stuff for FREESCO. You should know how to package your binaries and how to test them before you release them. I hope you enjoy your new hobby and hope to see you around in the FREESCO forums!