Installation of LiS
Installation of LiS is performed using a configuration script and then running "make". If you run "make" with no configuration file present, the makefile will run the configuration script automatically.
For the installation to proceed to its conclusion you must be logged in as "root". However, you can install LiS using a non-privileged user id. In this case the compilation of LiS will proceed but the installation of the resulting module will likely fail due to permission problems.
The easiest way to install LiS is to proceed as follows.
cd /usr/src/LiS-2.3 (Or wherever you installed the package) make make install
The version number in the above example is used for illustrative purposes only. Use the version number of the package that you downloaded.
The makefile will automatically run the LiS Configure script. You will be asked a series of questions by the configuration script and then the build will proceed.
The configuration script will make a symbolic link from /usr/src/LiS to whatever directory the Configure script was run from. This makes it easy to refer to the directory containing the latest installed version of LiS. This symbolic link will only be made if the Configure script (or initial "make") is run under "root".
Once the "make" is complete, enter make install to install the LiS utility programs in their proper places on your system.
If you want to un-install LiS, enter make very-clean. When it completes you can then do rm -rf /usr/src/LiS-2.2 (or whatever version of LiS you are removing). Note: The un-install does not remove entries from the /dev directory. For more information about un-installing LiS, click here.
Configuration
The configuration is extremely simple for the most common case of using LiS. This case occurs when you intend to run LiS as a loadable module installed in the directory /lib/modules/misc/kernel-version and your kernel source resides in the directory /usr/src/linux. For this case you can simply hit Enter/Return to select the default answer for each question and proceed quickly to the compilation phase.
If at any time you think that the configuration process has taken a wrong turn, you can terminate it by typing Ctrl-C (or your equivalent "intr" character). You can then start over from the beginning.
Re-Configuration
You can re-configure LiS by running the Configure script again at any time. The defaults for a re-configuration are the settings arrived at by the most recent previous run of Configure.
If you get your configuration hopelessly out of whack, just remove the file config.in and run Configure (or make). This will start over just as for a fresh installation.
When you change the configuration parameters it is a good idea to do a "make clean" before doing a "make".
Making LiS
You can make LiS by typing "make" in the LiS installation directory. The following make targets are defined.
Default target |
Compile LiS plus binary drivers into streams.o. Copy to modules directory if configured to do so. Compile utility programs. |
clean |
Remove all object code and utility programs. Leave configuration file in place. |
realclean |
Like "clean" except remove configuration files as well. |
very-clean |
Like "realclean" except remove the installed utility programs from their various directories. |
dep |
Make dependencies. Done automatically by default target. |
all |
Like default target except skip steps requiring root login. |
Utility Programs Made
In addition to the file streams.o, which contains LiS and any STREAMS drivers linked with it, the build procedure also makes the following utility programs. These programs are copied to the indicated directory if the "make" uses the default make target and if you are logged in as "root". These programs are documented separately.
/usr/sbin/streams |
Prints out statistics from running LiS. Sets debug mask for LiS. |
/usr/sbin/strconf |
Interprets STREAMS driver Config file and generates corresponding config.h and makenodes.c files. |
/usr/sbin/strmakenodes |
Program to make /dev entries for STREAMS drivers. The result of compiling makenodes.c. |
/usr/local/bin/strtst |
A comprehensive test program for STREAMS. |
/usr/local/bin/timetst |
Times round-trip delay from user application to STREAMS loopback driver. |
Of these programs, only strmakenodes and strconf are essential to the operation of LiS. Strmakenodes must be run prior to attempting to use any STREAMS application programs to make the proper entries in the /dev directory for STREAMS files.
The strconf program is needed for the build of LiS itself. However, the LiS build executes the program from the local LiS installation directory. Thus it is not necessary to copy this program to /usr/sbin in order to make streams.o.
Configuration Procedure
The following sections describe the steps of the Configure script.
Module or Kernel
The first question posed by the Configure script is whether you want to run LiS as a separate loadable module or link it into the kernel. The default is to run as a separate module. It is useful to link LiS into the kernel when you want to use GDB to debug kernel based STREAMS drivers.
Kernel Source Location
Configure asks you for the location of your kernel source tree. The default is /usr/src/linux and likely suffices for the vast majority of cases. Once Configure has this information it can determine the version of the kernel for which you are compiling LiS. The kernel version makes a difference in the amount of patching that must go into the kernel. Older kernels require patching, new ones do not.
If you are compiling for the kernel located in /usr/src/linux and the kernel version is 2.0.36 or 2.2.0 or later there is no patching of the kernel required to install LiS as a module. To link directly with the kernel, the "make" of LiS will insert a small patch into the kernel to cause LiS to be linked into the kernel and to arrange to call the LiS initialization routine at boot time.
We recommend that you use kernel version 2.0.36 or 2.2.x for installing the latest version of LiS.
Earlier versions of the kernel need patching for system call definitions. Kernel versions of the 2.0.24 vintage also need a patch to fix a bug in the semaphore code. All such patching is automatic. All patches made to the kernel are removed when LiS is removed from the system (see Removal).
If your kernel source has not had "menuconfig" run on it yet, Configure will propose doing so at this time automatically.
Likewise, if you have not done a "make dep" on your kernel source yet, Configure will propose doing so at this time automatically.
Kernel Version Verification
The LiS Configure script discovers the version of your kernel by looking in several places in your kernel source directory. If it cannot determine your kernel version the LiS configuration will terminate. The Configure script cannot proceed without this information.
The Configure script then asks for your verification of the kernel version for which LiS is to be compiled. Note, that the kernel for which you are compiling LiS does not have to be the kernel version on which your system is running. If you gave Configure a pathname to your intended kernel source version in the previous step this could be a different kernel version than the one that is running on your machine.
You can also enter a kernel version other than the one found in version.h at this time. However, entering such a version may cause the subsequent "make" to attempt to apply patches to the kernel source code that are not appropriate for that version of the source. So be careful about answering this question with anything other than an Enter/Return.
If the kernel version displayed does not match your idea of the version of the kernel that resides at the indicated location on disk, it is probably best to terminate the Configure program at this point and investigate rather than end up with inappropriate patches applied to your kernel source.
Automatic Kernel Building
If you answered the first question posed by Configure by indicating that you wish to have LiS linked directly in with the kernel, Configure now offers you the option of having a "make" in the LiS directory also proceed to a "make" in your indicated kernel directory. The default, selected by hitting Enter/Return, is not to do so.
If you elected to have an LiS build perform a kernel build automatically then Configure will now ask you which kernel build target you would like to have used. The default is bzImage, the theory being that you may be installing large STREAMS drivers into the kernel and therefore will need a "big" kernel image. LiS will add about 85K of code and data to your kernel size. The default is not bzlilo based on the idea that you likely are using this machine as a development machine and intend to run the resulting LiS module on a different system.
In any case, you can select the kernel "make" target that suits your needs.
LiS Module Location
If you have elected to build LiS as an installable module, rather than to link directly into the kernel, you will be asked whether or not you wish the "make" to copy the resulting streams.o file to the modules directory associated with your selected kernel version. The alternative is to have "make" build streams.o in the LiS directory and simply leave it there for manual copying later.
If you are intending to run LiS on the machine that you are using for the compilation you will probably want to answer this question with a "y". If you are intending to compile on this machine and copy the result to another machine for testing, then "n" is the appropriate answer here.
Debugging
If you intend to link LiS directly into the kernel and use GDB for kernel level debugging then you will likely want LiS to be compiled using the -g option. Configure asks you about this so that you can control whether to compile using -g or not.