My FREESCO page | Compiling for FREESCO

How to set up an environment for developing FREESCO applications

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.

Introduction

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: My email

[ Top ]

Purpose

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 ]

Limitations

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 ls, cd, etc.

[ Top ]

Environment

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.

Network overview

[ Top ]

Requirements

In order to setup the Zipslack, the following is needed:

  1. A pc. I use my daughters Celeron 566 with 256MB memory and it works well.
  2. A network card for the pc, preferably PCI, but not necessary
  3. Windows 95/98/ME. I use W98 but any of the other should do fine. This OS is needed as Zipslack is run from DOS
  4. An internet connection to be able to download the necessary software
  5. WinZip or any other 32-bit unzipper (the unzipper must be able to handle long file names)
  6. Spare time
  7. Patience!

[ Top ]

Preparing the machine

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:

  1. In Windows, ensure you have turned on the viewing of system/hidden files. Start Windows Explorer and find the menu called "Folder Options". In the dialog that pops up, select the tab called "View" and enable the displaying of all files. Also unselect the choice "Hide protected operating system files"
  2. In Windows Exlporer, look up the file C:\msdos.sys. Right-click the file and select "Properties". Unselect the "Write protected" and "Hidden" checkboxes.
  3. Start Notepad and load the file c:\msdos.sys into the editor
  4. Do the necessary changes and save the file.
  5. Reboot the computer. Now the boot menu should show up and you should be able to boot into DOS.

Milestone 2: You should now be able to boot your machine into DOS (as well as Windows) using the boot menu.

[ Top ]

Installing Zipslack

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:

  1. Boot your develop machine into Windows
  2. Download Zipslack from ftp://ftp.slackware.com/pub/slackware/slackware-3.9/zipslack/zipslack.zip.
  3. Unzip the file to the root of the FAT-partition you run W98 on, usually C:. This produces a directory called linux in the root of the drive
  4. Inside the directory there is a batch file called linux.bat. This file is used for starting Zipslack. Start Notepad and load the file into the editor.
  5. The file contains several rows with the following structure:

    rem \linux\loadlin \linux\vmlinuz root=/dev/xxxN rw

    These rows tells where to find the Linux kernel. Each row specifies a certain location. Most of the rows start with the word rem which 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

    to

    rem \linux\loadlin \linux\vmlinuz root=/dev/sda4 rw

    In order to find the kernel, uncomment the row

    rem \linux\loadlin \linux\vmlinuz root=/dev/hda1 rw

    so it reads

    \linux\loadlin \linux\vmlinuz root=/dev/hda1 rw

    Save your changes and exit the editor
  6. Copy the linux.bat file 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

linux

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 "halt".

Milestone 3: You should now be able to boot into Zipslack.

[ Top ]

Updating the kernel

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.

Getting the new kernel sources

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 linux (/usr/src/linux) and in order to build the kernel we enter this directory:

cd linux

[ Top ]

Configuring and building the kernel

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

make menuconfig

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=1M, 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:

TeCuMSeH:

Isn't it advisable to download the Freesco kernel source (because it's patched a bit) instead of the kernel at kernel.org?

Lightning:

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 ]

Configuring Zipslack

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.

Networking

The first thing to do is to get your Zipslack up on your network. To do this, run

netconfig

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

/etc/rc.d/rc.inet1 restart

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

passwd root

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

mcedit /etc/securetty

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

root

so it reads

#root

Save changes and exit the editor. Once again reboot your system (or use /etc/rc.d/rc.inet1 restart).

Milestone 6: You should be able to telnet and ftp to your Zipslack as root from any machine on your LAN.

[ Top ]

VNC

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 ]

Getting the VNC source

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 ]

Updating Zipslack

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 /pub/slackware/slackware-3.9/slakware/x1/:

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

installpk xfnts.tgz

If you have all packages in the same directory (and no other *.tgz files there), you can run

installpkg *.tgz

to install all packages at once. After installing the libraries we need to update the system with the new libs. This is done with

ldconfig

Your system is now ready for building VNC and Xvnc.

[ Top ]

Building VNC and Xvnc

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:

make

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 /usr/local/bin:

cd ..
./vncinstall /usr/local/bin

When finished, it is possible to start Xvnc with the command

vncserver

By default it will use display 1, but that can be specified when starting the server. Eg:

vncserver :3

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:

192.168.0.100:3

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 /etc/rc.d/rc.local

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 ]

Useful packages

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 ]

Compiling and packaging packages

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:

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 ]

Testing packages using Bochs

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 ]

Installing Bochs

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:

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 ]

Using Bochs

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):

  1. Run the FREESCO HD configuration (F032-HD.bxrc). This will boot a FREESCO from a HD image (F032-HD.img). Remember to do the necessary changes in the *.bxrc file. Once FREESCO is booted, run the setup an configure it as you like (NICs, etc). It might be a good idea to disable servers like telnet/ftp/http/control/oident/print/DNS to make FREESCO boot faster.
  2. Once FREESCO runs as you like you should make a copy of the HD image for future use. Shut down the FREESCO emulation and make a copy of the HD image, naming it FREESCO_SETUP.img or whatever. This copy of the image is useful whenever you want to start with a fresh HD installation of FREESCO.
  3. Now run the HD configuration again and start FREESCO. When up and running, try to install your package (which you should have uploaded to a server of yours). During this stage, you'll most probably find errors in your package. Go back to your Zipslack and correct the package and upload a fixed version to your server.
  4. By now, the FREESCO installation on your HD image has one version of your package installed. At this moment you want to try the new version of the package and you probably want to do that on a clean FREESCO. This is easy achieved. Just remove your original HD image, then make a copy of FREESCO_SETUP.img. Rename the new copy to the original name (F032-HD.img) and start the HD setup. You should find yourself in a clean copy of FREESCO which is ready for your updated package.
  5. Iterate the steps above untill your package behaves as supposed.

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 ]

Finishing words

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!

/Fredrik