diff --git a/handbook/dialup.sgml b/handbook/dialup.sgml index 322d58b3ea..c5b07b19f3 100644 --- a/handbook/dialup.sgml +++ b/handbook/dialup.sgml @@ -1,810 +1,810 @@ Dialup access

Contributed by &a.ghelmer;. This document provides suggestions for configuring a FreeBSD system to handle dialup modems. This document is written based on the author's experience with FreeBSD versions 1.0, 1.1, and 1.1.5.1 (and experience with dialup modems on other UNIX-like operating systems); however, this document may not answer all of your questions or provide examples specific enough to your environment. The author cannot be responsible if you damage your system or lose data due to attempting to follow the suggestions here. Prerequisites

To begin with, the author assumes you have some basic knowledge of FreeBSD. You need to have FreeBSD installed, know how to edit files in a UNIX-like environment, and how to look up manual pages on the system. As discussed below, you'll need certain versions of FreeBSD, and knowledge of some terminology & modem and cabling. FreeBSD Version

First, it is assumed that you are using FreeBSD version 1.1 or higher (including versions 2.x). FreeBSD version 1.0 included two different serial drivers, which complicates the situation. Also, the serial device driver (Terminology

A quick rundown of terminology: If you need more information about these terms and data communications in general, the author remembers reading that External vs. Internal Modems

External modems seem to be more convenient for dialup, because external modems often can be semi-permanently configured via parameters stored in non-volatile RAM and they usually provide lighted indicators that display the state of important RS-232 signals. Blinking lights impress visitors, but lights are also very useful to see whether a modem is operating properly. Internal modems usually lack non-volatile RAM, so their configuration may be limited only to setting DIP switches. If your internal modem has any signal indicator lights, it is probably difficult to view the lights when the system's cover is in place. Modems and Cables

A background knowledge of these items is assumed You know how to connect your modem to your computer so that the two can communicate (unless you have an internal modem, which does not need such a cable) You are familiar with your modem's command set, or know where to look up needed commands You know how to configure your modem (probably via a terminal communications program) so you can set the non-volatile RAM parameters The first, connecting your modem, is usually simple - most straight-through serial cables work without any problems. You need to have a cable with appropriate connectors (DB-25 or DB-9, male or female) on each end, and the cable must be a DCE-to-DTE cable with these signals wired: Transmitted Data ( Received Data ( Request to Send ( Clear to Send ( Data Set Ready ( Data Terminal Ready ( Carrier Detect ( Signal Ground ( FreeBSD needs the Serial Interface Considerations

FreeBSD supports NS8250-, NS16450-, NS16550-, and NS16550A-based EIA RS-232C (CCITT V.24) communications interfaces. The 8250 and 16450 devices have single-character buffers. The 16550 device provides a 16-character buffer, which allows for better system performance. (Bugs in plain 16550's prevent the use of the 16-character buffer, so use 16550A's if possible). Because single-character-buffer devices require more work by the operating system than the 16-character-buffer devices, 16550A-based serial interface cards are much prefered. If the system has many active serial ports or will have a heavy load, 16550A-based cards are better for low-error-rate communications. Quick Overview

Here is the process that FreeBSD follows to accept dialup logins. A /dev/ttyd0, for our example). The command 4850 ?? I 0:00.09 /usr/libexec/getty V19200 ttyd0 When a user dials the modem's line and the modems connect, the /usr/bin/login, which completes the login by asking for the user's password and then starting the user's shell. Let's dive into the configuration... Kernel Configuration

FreeBSD kernels typically come prepared to search for four serial ports, known in the PC-DOS world as /sbin/dmesg command to replay the kernel's boot messages. In particular, look for messages that start with the characters /sbin/dmesg | grep 'sio' For example, on a system with four serial ports, these are the serial-port specific kernel boot messages: sio0 at 0x3f8-0x3ff irq 4 on isa sio0: type 16550A sio1 at 0x2f8-0x2ff irq 3 on isa sio1: type 16550A sio2 at 0x3e8-0x3ef irq 5 on isa sio2: type 16550A sio3 at 0x2e8-0x2ef irq 9 on isa sio3: type 16550A If your kernel does not recognize all of your serial ports, you will probably need to configure a custom FreeBSD kernel for your system. Please see the BSD System Manager's Manual chapter on ``Building Berkeley Kernels with Config'' [the source for which is in /usr/src/share/doc/smm] and ``FreeBSD Configuration Options'' [in /sys/conf/options and in /sys/arch/conf/options.arch, with arch for example being i386] for more information on configuring and building kernels. You may have to unpack the kernel source distribution if have not installed the system sources already (srcdist/srcsys.?? in FreeBSD 1.1, srcdist/sys.?? in FreeBSD 1.1.5.1, or the entire source distribution in FreeBSD 2.0) to be able to configure and build kernels. Create a kernel configuration file for your system (if you have not already) by /sys/i386/conf. Then, if you are creating a new custom configuration file, copy the file GENERICAH (or GENERICBT, if you have a BusTek SCSI controller on FreeBSD 1.x) to device sio0 at isa? port "IO_COM1" tty irq 4 vector siointr device sio1 at isa? port "IO_COM2" tty irq 3 vector siointr device sio2 at isa? port "IO_COM3" tty irq 5 vector siointr device sio3 at isa? port "IO_COM4" tty irq 9 vector siointr You can comment-out or completely remove lines for devices you do not have. If you have a multiport serial board, such as the Boca Board BB2016, please see the cannot share interrupts on ISA-bus PCs (multiport boards have on-board electronics that allow all the 16550A's on the board to share one or two interrupt request lines). When you are finished adjusting the kernel configuration file, use the program Device Special Files

Most devices in the kernel are accessed through ``device special files'', which are located in the /dev directory. The /dev/ttyd? (dial-in) and /dev/cua0? (call-out) devices. On FreeBSD version 1.1.5 and higher, there are also initialization devices (/dev/ttyid? and /dev/cuai0?) and locking devices (/dev/ttyld? and /dev/cual0?). The initialization devices are used to initialize communications port parameters each time a port is opened, such as crtscts for modems which use CTS/RTS signaling for flow control. The locking devices are used to lock flags on ports to prevent users or programs changing certain parameters; see the manual pages Making Device Special Files

A shell script called /dev directory manages the device special files. (The manual page for /dev and issue the command /dev/ttyd? device special files, but also creates the /dev/cua0? (and all of the initializing and locking special files under FreeBSD 1.1.5 and up) and removes the hardwired terminal special file /dev/tty0?, if it exists. After making new device special files, be sure to check the permissions on the files (especially the /dev/cua* files) to make sure that only users who should have access to those device special files can read & write on them - you probably do not want to allow your average user to use your modems to dialout. The default permissions on the /dev/cua* files should be sufficient: crw-rw---- 1 uucp dialer 28, 129 Feb 15 14:38 /dev/cua01 crw-rw---- 1 uucp dialer 28, 161 Feb 15 14:38 /dev/cuai01 crw-rw---- 1 uucp dialer 28, 193 Feb 15 14:38 /dev/cual01 These permissions allow the user Configuration Files

There are three system configuration files in the /etc directory that yo will probably need to edit to allow dialup access to your FreeBSD system. The first, /etc/gettytab, contains configuration information for the /usr/libexec/getty daemon. Second, /etc/ttys holds information that tells /sbin/init what /etc/rc.serial script if you have FreeBSD 1.1.5.1 or higher; otherwise, you can initialize ports in the /etc/rc.local script. There are two schools of thought regarding dialup modems on UNIX. One group likes to configure their modems and system so that no matter at what speed a remote user dials in, the local computer-to-modem RS-232 interface runs at a locked speed. The benefit of this configuration is that the remote user always sees a system login prompt immediately. The downside is that the system does not know what a user's true data rate is, so full-screen programs like Emacs will not adjust their screen-painting methods to make their response better for slower connections. The other school configures their modems' RS-232 interface to vary its speed based on the remote user's connection speed. For example, V.32bis (14.4 Kbps) connections to the modem might make the modem run its RS-232 interface at 19.2 Kbps, while 2400 bps connections make the modem's RS-232 interface run at 2400 bps. Because <Enter> key until they see a recognizable prompt. If the data rates do not match, /etc/gettytab

/etc/gettytab is a Locked-Speed Config

If you are locking your modem's data communications rate at a particular speed, you probably will not need to make any changes to /etc/gettytab. Matching-Speed Config

You will need to setup an entry in /etc/gettytab to give # # Fast dialup terminals, 2400/1200/300 rotary (can start either way) # D2400|d2400|Fast-Dial-2400:\ :nx=D1200:tc=2400-baud: 3|D1200|Fast-Dial-1200:\ :nx=D300:tc=1200-baud: 5|D300|Fast-Dial-300:\ :nx=D2400:tc=300-baud: If you have a higher speed modem, you will probably need to add an entry in /etc/gettytab; here is an entry you could use for a 14.4 Kbps modem with a top interface speed of 19.2 Kpbs: # # Additions for a V.32bis Modem # um|V300|High Speed Modem at 300,8-bit:\ :nx=V19200:tc=std.300: un|V1200|High Speed Modem at 1200,8-bit:\ :nx=V300:tc=std.1200: uo|V2400|High Speed Modem at 2400,8-bit:\ :nx=V1200:tc=std.2400: up|V9600|High Speed Modem at 9600,8-bit:\ :nx=V2400:tc=std.9600: uq|V19200|High Speed Modem at 19200,8-bit:\ :nx=V9600:tc=std.19200: On FreeBSD 1.1.5 and later, this will result in 8-bit, no parity connections. Under FreeBSD 1.1, add std. entries at the top of the file for 8 bits, no parity; otherwise, the default is 7 bits, even parity. The example above starts the communications rate at 19.2 Kbps (for a V.32bis connection), then cycles through 9600 bps (for V.32), 2400 bps, 1200 bps, 300 bps, and back to 19.2 Kbps. Communications rate cycling is implemented with the # # Additions for a V.32bis or V.34 Modem # Starting at 57.6 Kpbs # vm|VH300|Very High Speed Modem at 300,8-bit:\ :nx=VH57600:tc=std.300: vn|VH1200|Very High Speed Modem at 1200,8-bit:\ :nx=VH300:tc=std.1200: vo|VH2400|Very High Speed Modem at 2400,8-bit:\ :nx=VH1200:tc=std.2400: vp|VH9600|Very High Speed Modem at 9600,8-bit:\ :nx=VH2400:tc=std.9600: vq|VH57600|Very High Speed Modem at 57600,8-bit:\ :nx=VH9600:tc=std.57600: If you have a slow CPU or a heavily loaded system and you dobnot have 16550A-based serial ports, you may receive sio ``silo'' errors at 57.6 Kbps. /etc/ttys

/etc/ttys is the list of /etc/ttys also provides security information to /etc/ttys or add new lines to make ttyd0 "/usr/libexec/getty xxx" dialup on The first item in the above line is the device special file for this entry - /dev/ttyd0 is the file that this "/usr/libexec/getty (secure, but it should only be used for terminals which are physically secure (such as the system console). The default terminal type (/etc/ttys, you may send the kill -1 1 to send the signal. If this is your first time setting up the system, though, you may want to wait until your modem(s) are properly configured and connected before signaling Locked-Speed Config

For a locked-speed configuration, your ttyd0 "/usr/libexec/getty std.19200" dialup on If your modem is locked at a different data rate, substitute the appropriate name for the std. entry for /etc/gettytab for your modem's data rate. Matching-Speed Config

In a matching-speed configuration, your /etc/gettytab. For example, if you added the above suggested entry for a matching-speed modem that starts at 19.2 Kbps (the ttyd0 "/usr/libexec/getty V19200" dialup on /etc/rc.serial or /etc/rc.local

High-speed modems, like V.32, V.32bis, and V.34 modems, need to use hardware (RTS/CTS) flow control. You can add /etc/rc.serial on FreeBSD 1.1.5.1 and up, or /etc/rc.local on FreeBSD 1.1, to set the hardware flow control flag in the FreeBSD kernel for the modem ports. For example, on a sample FreeBSD 1.1.5.1 system, /etc/rc.serial reads: #!/bin/sh # # Serial port initial configuration stty -f /dev/ttyid1 crtscts stty -f /dev/cuai01 crtscts which sets the # Set serial ports to use RTS/CTS flow control stty -f /dev/ttyd0 crtscts stty -f /dev/ttyd1 crtscts stty -f /dev/ttyd2 crtscts stty -f /dev/ttyd3 crtscts Since there is no initialization device special file on FreeBSD 1.1, one has to just set the flags on the sole device special file and hope the flags aren't cleared by a miscreant. Modem Settings

If you have a modem whose parameters may be permanently set in non-volatile RAM, you will need to use a terminal program (such as Telix under PC-DOS or Disable XON/XOFF flow control Quiet mode (no result codes) No command echo Please read the documentation for your modem to find out what commands and/or DIP switch settings you need to give it. For example, to set the above parameters on a USRobotics Sportster 14,400 external modem, one could give these commands to the modem: ATZ AT&C1&D2&H1&I0&R2&W You might also want to take this opportunity to adjust other settings in the modem, such as whether it will use V.42bis and/or MNP5 compression. The USR Sportster 14,400 external modem also has some DIP switches that need to be set; for other modems, perhaps you can use these settings as an example: Switch 1: UP - DTR Normal Switch 2: Do not care (Verbal Result Codes/Numeric Result Codes) Switch 3: UP - Suppress Result Codes Switch 4: DOWN - No echo, offline commands Switch 5: UP - Auto Answer Switch 6: UP - Carrier Detect Normal Switch 7: UP - Load NVRAM Defaults Switch 8: Do not care (Smart Mode/Dumb Mode) Result codes should be disabled/suppressed for dialup modems to avoid problems that can occur if Locked-speed Config

For a locked-speed configuration, you will need to configure the modem to maintain a constant modem-to-computer data rate independent of the communications rate. On a USR Sportster 14,400 external modem, these commands will lock the modem-to-computer data rate at the speed used to issue the commands: ATZ AT&B1&W Matching-speed Config

For a variable-speed configuration, you will need to configure your modem to adjust its serial port data rate to match the incoming call rate. On a USR Sportster 14,400 external modem, these commands will lock the modem's error-corrected data rate to the speed used to issue the commands, but allow the serial port rate to vary for non-error-corrected connections: ATZ AT&B2&W Checking the Modem's Configuration

Most high-speed modems provide commands to view the modem's current operating parameters in a somewhat human-readable fashion. On the USR Sportster 14,400 external modems, the command Troubleshooting

Here are a few steps you can follow to check out the dialup modem on your system. Checking out the FreeBSD system

Hook up your modem to your FreeBSD system, boot the system, and, if your modem has status indication lights, watch to see whether the modem's 114 ?? I 0:00.10 /usr/libexec/getty V19200 ttyd0 115 ?? I 0:00.10 /usr/libexec/getty V19200 ttyd1 If you see something different, like this: 114 d0 I 0:00.10 /usr/libexec/getty V19200 ttyd0 ^^ and the modem has not accepted a call yet, this means that /etc/ttys to see if there are any mistakes there. Also, check the log file /var/log/messages to see if there are any log messages from /etc/ttys and /etc/gettytab, as well as the appropriate device special files /dev/ttyd?, for any mistakes, missing entries, or missing device special files. Try Dialing In

Try dialing into the system; be sure to use 8 bits, no parity, 1 stop bit on the remote system. If you do not get a prompt right away, or get garbage, try pressing <Enter> about once per second. If you still do not see a BREAK. If you are using a high-speed modem to do the dialing, try dialing again after locking the dialing modem's interface speed (via AT&B1 on a USR Sportster, for example). If you still cannot get a /etc/gettytab again and double-check that The initial capability name specified in /etc/ttys for the line matches a name of a capability in /etc/gettytab Each Each If you dial but the modem on the FreeBSD system will not answer, make sure that the modem is configured to answer the phone when Acknowledgments

Thanks to these people for comments and advice: -&a.kelly for a number of good suggestions +&a.kelly for a number of good suggestions diff --git a/handbook/linuxemu.sgml b/handbook/linuxemu.sgml index e0a0f47350..384c549974 100644 --- a/handbook/linuxemu.sgml +++ b/handbook/linuxemu.sgml @@ -1,700 +1,700 @@ - + Linux Emulation

Contributed by &a.brian and &a.rich; How to install the Linux emulator

Linux emulation in FreeBSD has reached a point where it is possible to run a large fraction of Linux binaries in both a.out and ELF format. The linux emulation in the -STABLE branch is capable of running Linux DOOM and Mathematica; the version present in FreeBSD-CURRENT is vastly more capable and runs all these as well as Quake, Abuse, IDL, netrek for Linux and a whole host of other programs. There are some Linux-specific operating system features that are not supported on FreeBSD. Linux binaries will not work on FreeBSD if they use the Linux /proc filesystem (which is different from the optional FreeBSD /proc filesystem) or i386-specific calls, such as enabling virtual 8086 mode.

To tell whether your kernel is configured for Linux compatibility simply run any Linux binary. If it prints the error message linux-executable: Exec format error. Wrong Architecture. then you do not have linux compatibility support and you need to configure and install a new kernel. Depending on which version of FreeBSD you are running, how you get Linux-emulation up will vary slightly: Installing Linux Emulation in 2.1-STABLE

The GENERIC kernel in 2.1-stable is not configured for linux compatibility so you you must reconfigure your kernel for it. There are two ways to do this: 1. linking the emulator statically in the kernel itself and 2. configuring your kernel to dynamically load the linux loadable kernel module (LKM).

To enable the emulator, add the following to your configuration file (c.f. /sys/i386/conf/LINT): options "COMPAT_LINUX" If you want to run doom or other applications that need shared memory also add the following. options SYSVSHM The linux system calls require 4.3 BSD system call compatibility. So make sure you have the following. options "COMPAT_43" If you prefer to statically link the emulator in the kernel rather than use the loadable kernel module (LKM), then add options LINUX Then run config and install the new kernel as described in the section. If you decide to use the LKM you must also install the loadable module. A mismatch of versions between the kernel and loadable module can cause the kernel to crash, so the safest thing to do is to reinstall the LKM when you install the kernel. % cd /usr/src/lkm/linux % make all install Once you have installed the kernel and the LKM, you can invoke `linux' as root to load the LKM. % linux Linux emulator installed Module loaded as ID 0 % To see whether the LKM is loaded, run `modstat'. % modstat Type Id Off Loadaddr Size Info Rev Module Name EXEC 0 3 f0baf000 0018 f0bb4000 1 linux_emulator % You can cause the LKM to be loaded when the system boots in either of two ways. On FreeBSD-CURRENT and FreeBSD-STABLE enable it in /etc/sysconfig linux=YES by changing it from NO to YES. FreeBSD 2.1 RELEASE and earlier do not have such a line and on those you will need to edit /etc/rc.local to add the following line. linux Installing Linux Emulation in 2.2-CURRENT

In -current it is no longer necessary to specify options "LINUX" or options "COMPAT_LINUX". Linux emulation is done with an LKM (``Loadable Kernel Module'') so it can be installed on the fly without having to reboot. You will need the following things in your startup files, however: In /etc/sysconfig, you need the following line: linux=YES This, in turn, triggers the following action in /etc/rc.i386: # Start the Linux binary emulation if requested. if [ "X${linux}" = X"YES" ]; then echo -n ' '; linux # XXX BOGUS - Linux script shouldn't make any output on success fi

If you want to verify it is running, modstat will do that: % modstat Type Id Off Loadaddr Size Info Rev Module Name EXEC 0 4 f09e6000 001c f09ec010 1 linux_mod % However, there have been reports that this fails on some FreeBSD-current systems. If for some reason you cannot load the linux LKM, then statically link the emulator in the kernel by adding options LINUX to your kernel config file. Then run config and install the new kernel as described in the section. Installing Linux Runtime Libraries Installing using the linux_lib port

Most linux applications use shared libraries, so you are still not done until you install the shared libraries. It is possible to do this by hand, however, it is vastly simpler to just grab the linux_lib port: % cd /usr/ports-current/emulators/linux_lib % make all install and you should have a working linux emulator. Legend (and the mail archives :-) seems to hold that Linux emulation works best with linux binaries linked against the ZMAGIC libraries; QMAGIC libraries (such as those used in Slackware V2.0) may tend to give the Linuxulator heartburn. As of this writing (March 1996) ELF emulation is still in the formulative stages but seems to work pretty well. Also, expect some programs to complain about incorrect minor versions. In general this does not seem to be a problem. Installing libraries manually

If you don't have the ``ports'' distribution, you can install the libraries by hand instead. You will need the Linux shared libraries that the program depends on and the runtime linker. Also, you will need to create a "shadow root" directory, /compat/linux, for Linux libraries on your FreeBSD system. Any shared libraries opened by Linux programs run under FreeBSD will look in this tree first. So, if a Linux program loads, for example, /lib/libc.so, FreeBSD will first try to open /compat/linux/lib/libc.so, and if that does not exist then it will try /lib/libc.so. Shared libraries should be installed in the shadow tree /compat/linux/lib rather than the paths that the Linux ld.so reports. FreeBSD-current works slightly differently with respect to /compat/linux. On -current, all files, not just libraries, are searched for from the ``shadow root'' /compat/linux. Generally, you will need to look for the shared libraries that Linux binaries depend on only the first few times that you install a Linux program on your FreeBSD system. After a while, you will have a sufficient set of Linux shared libraries on your system to be able to run newly imported Linux binaries without any extra work. How to install additional shared libraries

What if you install the linux_lib port and your application still complains about missing shared libraries? How do you know which shared libraries Linux binaries need, and where to get them? Basically, there are 2 possibilities (when following these instructions: you will need to be root on your FreeBSD system to do the necessary installation steps).

If you have access to a Linux system, see what shared libraries it needs, and copy them to your FreeBSD system. Example: you have just ftp'ed the Linux binary of Doom. Put it on the Linux system you have access to, and check which shared libraries it needs by running `ldd linuxxdoom': % ldd linuxxdoom libXt.so.3 (DLL Jump 3.1) => /usr/X11/lib/libXt.so.3.1.0 libX11.so.3 (DLL Jump 3.1) => /usr/X11/lib/libX11.so.3.1.0 libc.so.4 (DLL Jump 4.5pl26) => /lib/libc.so.4.6.29

You would need go get all the files from the last column, and put them under /compat/linux, with the names in the first column as symbolic links pointing to them. This means you eventually have these files on your FreeBSD system: /compat/linux/usr/X11/lib/libXt.so.3.1.0 /compat/linux/usr/X11/lib/libXt.so.3 -> libXt.so.3.1.0 /compat/linux/usr/X11/lib/libX11.so.3.1.0 /compat/linux/usr/X11/lib/libX11.so.3 -> libX11.so.3.1.0 /compat/linux/lib/libc.so.4.6.29 /compat/linux/lib/libc.so.4 -> libc.so.4.6.29

Note that if you already have a Linux shared library with a matching major revision number to the first column of the 'ldd' output, you will not need to copy the file named in the last column to your system, the one you already have should work. It is advisable to copy the shared library anyway if it is a newer version, though. You can remove the old one, as long as you make the symbolic link point to the new one. So, if you have these libraries on your system: /compat/linux/lib/libc.so.4.6.27 /compat/linux/lib/libc.so.4 -> libc.so.4.6.27 and you find a new binary that claims to require a later version according to the output of ldd: libc.so.4 (DLL Jump 4.5pl26) -> libc.so.4.6.29 If it is only one or two versions out of date in the in the trailing digit then do not worry about copying /lib/libc.so.4.6.29 too, because the program should work fine with the slightly older version. However, if you like you can decide to replace the libc.so anyway, and that should leave you with: /compat/linux/lib/libc.so.4.6.29 /compat/linux/lib/libc.so.4 -> libc.so.4.6.29

Please note that the symbolic link mechanism is only needed for Linux binaries, the FreeBSD runtime linker takes care of looking for matching major revision numbers itself, you do not need to worry about that. Configuring the ld.so -- for FreeBSD-current only

This section applies only to FreeBSD-current only. Those running FreeBSD-stable should skip this section.

Finally, if you run FreeBSD-current you must make sure that you have the Linux runtime linker and its config files on your system. You should copy these files from the Linux system to their appropriate place on your FreeBSD system (to the /compat/linux tree): /compat/linux/lib/ld.so /compat/linux/etc/ld.so.config

If you do not have access to a Linux system, you should get the extra files you need from various ftp sites. Information on where to look for the various files is appended below. For now, let us assume you know where to get the files.

Retrieve the following files (all from the same ftp site to avoid any version mismatches), and install them under /compat/linux (i.e. /foo/bar is installed as /compat/linux/foo/bar): /sbin/ldconfig /usr/bin/ldd /lib/libc.so.x.y.z /lib/ld.so

ldconfig and ldd do not necessarily need to be under /compat/linux, you can install them elsewhere in the system too. Just make sure they do not conflict with their FreeBSD counterparts. A good idea would be to install them in /usr/local/bin as ldconfig-linux and ldd-linux.

Create the file /compat/linux/etc/ld.so.conf, containing the directories in which the Linux runtime linker should look for shared libs. It is a plain text file, containing a directory name on each line. /lib and /usr/lib are standard, you could add the following: /usr/X11/lib /usr/local/lib

When a linux binary opens a library such as /lib/libc.so the emulator maps the name to /compat/linux/lib/libc.so internally. All linux libraries should be installed under /compat/linux (e.g. /compat/linux/lib/libc.so, /compat/linux/usr/X11/lib/libX11.so, etc.) in order for the emulator to find them.

Those running FreeBSD-current should run the Linux ldconfig program. % cd /compat/linux/lib % /compat/linux/sbin/ldconfig

Ldconfig is statically linked, so it does not need any shared libraries to run. It creates the file /compat/linux/etc/ld.so.cache which contains the names of all the shared libraries. It should rerun to recreate this file whenever you install additional shared libraries. On FreeBSD-stable do not install /compat/linux/etc/ld.so.cache or run ldconfig becuase in FreeBSD-stable the syscalls are implemented differently and ldconfig is not needed or used.

You should now be set up for Linux binaries which only need a shared libc. You can test this by running the Linux ldd on itself. Suppose that you have it installed as ldd-linux, it should produce something like: % ldd-linux `which ldd-linux` libc.so.4 (DLL Jump 4.5pl26) => /lib/libc.so.4.6.29

This being done, you are ready to install new Linux binaries. Whenever you install a new Linux program, you should check if it needs shared libraries, and if so, whether you have them installed in the /compat/linux tree. To do this, you run the Linux version ldd on the new program, and watch its output. ldd (see also the manual page for ldd(1)) will print a list of shared libraries that the program depends on, in the form majorname (jumpversion) => fullname.

If it prints "not found" instead of fullname it means that you need an extra library. Which library this is, is shown in majorname, which will be of the form libXXXX.so.N You will need to find a libXXXX.so.N.mm on a Linux ftp site, and install it on your system. The XXXX (name) and N (major revision number) should match; the minor number(s) mm are less important, though it is advised to take the most recent version. Configuring the host name resolver

If DNS does not work or you get the messages resolv+: "bind" is an invalid keyword resolv+: "hosts" is an invalid keyword then you need to configure a /compat/linux/etc/host.conf file containing: order hosts, bind multi on where the order here specifies that /etc/hosts is searched first and DNS is searched second. When /compat/linux/etc/host.conf is not installed linux applications find FreeBSD's /etc/host.conf and complain about the incompatible FreeBSD syntax. You should remove `bind,' if you have not configured a name-server using the /etc/resolv.conf file.

Lastly, those who run FreeBSD-stable need to set an the RESOLV_HOST_CONF environment variable so that applications will know how to search the host tables. If you run FreeBSD-current you can skip this. For the /bin/csh shell use: setenv RESOLV_HOST_CONF /compat/linux/etc/host.conf For /bin/sh use: RESOLV_HOST_CONF=/compat/linux/etc/host.conf; export RESOLV_HOST_CONF Finding the necessary files

Note: the information below is valid as of the time this document was written, but certain details such as names of ftp sites, directories and distribution names may have changed by the time you read this.

Linux is distributed by several groups that make their own set of binaries that they distribute. Each distribution has its own name, like ``Slackware'' or ``Yggdrasil''. The distributions are available on a lot of ftp sites. Sometimes the files are unpacked, and you can get the individual files you need, but mostly they are stored in distribution sets, usually consisting of subdirectories with gzipped tar files in them. The primary ftp sites for the distributions are: sunsite.unc.edu:/pub/Linux/distributions tsx-11.mit.edu:/pub/linux/distributions

Some European mirrors: ftp.luth.se:/pub/linux/distributions ftp.demon.co.uk:/pub/linux/distributions src.doc.ic.ac.uk:/packages/linux/distributions

For simplicity, let us concentrate on Slackware here. This distribution consists of a number of subdirectories, containing separate packages. Normally, they are controlled by an install program, but you can retrieve files "by hand" too. First of all, you will need to look in the "contents" subdir of the distribution. You will find a lot of small text files here describing the contents of the separate packages. The fastest way to look something up is to retrieve all the files in the contents subdirectory, and grep through them for the file you need. Here is an example of a list of files that you might need, and in which contents-file you will find it by grepping through them: Library Package ld.so ldso ldconfig ldso ldd ldso libc.so.4 shlibs libX11.so.6.0 xf_lib libXt.so.6.0 xf_lib libX11.so.3 oldlibs libXt.so.3 oldlibs

So, in this case, you will need the packages ldso, shlibs, xf_lib and oldlibs. In each of the contents-files for these packages, look for a line saying ``PACKAGE LOCATION'', it will tell you on which `disk' the package is, in our case it will tell us in which subdirectory we need to look. For our example, we would find the following locations: Package Location ldso diska2 shlibs diska2 oldlibs diskx6 xf_lib diskx9

The locations called ``diskXX'' refer to the ``slakware/XX'' subdirectories of the distribution, others may be found in the ``contrib'' subdirectory. In this case, we could now retrieve the packages we need by retrieving the following files (relative to the root of the Slackware distribution tree): slakware/a2/ldso.tgz slakware/a2/shlibs.tgz slakware/x6/oldlibs/tgz slakware/x9/xf_lib.tgz

Extract the files from these gzipped tarfiles in your /compat/linux directory (possibly omitting or afterwards removing files you don't need), and you are done.

See also: ftp.freebsd.org:pub/FreeBSD/2.0.5-RELEASE/xperimnt/linux-emu/README /usr/src/sys/i386/ibcs2/README.iBCS2 How to Install Mathematica on FreeBSD

Contributed by &a.rich and &a.chuck This document shows how to install the Linux binary distribution of Mathematica 2.2 on FreeBSD 2.1.

Mathematica supports Linux but not FreeBSD as it stands. So once you have configured your system for Linux compatibility you have most of what you need to run Mathematica.

For those who already have the student edition of Mathematica for DOS the cost of upgrading to the Linux version at the time this was written, March 1996, was -$45.00. It can be ordered directly from Wolfram at +$45.00. It can be ordered directly from Wolfram at (217) 398-6500 and paid for by credit card. Unpacking the Mathematica distribution

The binaries are currently distributed by Wolfram on CDROM. The CDROM has about a dozen tar files, each of which is a binary distribution for one of the supported architectures. The one for Linux is named LINUX.TAR. You can, for example, unpack this into /usr/local/Mathematica: % cd /usr/local % mkdir Mathematica % cd Mathematica % tar -xvf /cdrom/LINUX.TAR Obtaining your Mathematica Password

Before you can run Mathematica you will have to obtain a password from Wolfram that corresponds to your `machine ID.'

Once you have installed the linux compatibility runtime libraries and unpacked the mathematica you can obtain the `machine ID' by running the program `mathinfo' in the Install directory. % cd /usr/local/Mathematica/Install % mathinfo LINUX: 'ioctl' fd=5, typ=0x89(), num=0x27 not implemented richc.isdn.bcm.tmc.edu 9845-03452-90255 % So, for example, the `machine ID' of `richc' is `9845-03452-90255'. You can ignore the message about the ioctl that is not implemented. It won't prevent Mathematica from running in any way and you can safely ignore it, though you will see the message every time you run Mathematica.

When you register with Wolfram, either by email, phone or fax, you'll give them the 'machine ID' and they will respond with a corresponding password consisting of groups of numbers. You need to add them both along with the machine name and license number in your mathpass file. You can do this by invoking: % cd /usr/local/Mathematica/Install % math.install It will ask you to enter your license number and the Wolfram supplied password. If you get them mixed up or for some reason the math.install fails, That's OK, because you can simply edit the file 'mathpass' in this same directory to correct the info manually.

After getting past the password, math.install will ask you if you accept their canned install defaults, or if you want to use your own. If you are like us and distrust all install programs, you probably want to specify the actual directories. Beware. Although the math.install program asks you to specify directories, it won't create them for you, so you should perhaps have a second window open with another shell so that you can create them before you give them to the install program. Or, if it fails, you can create the directories and then restart the math.install program. The directories we chose to create beforehand and specify to math.install were: /usr/local/Mathematica/bin for binaries /usr/local/Mathematica/man/man1 for man pages /usr/local/Mathematica/lib/X11 for the XKeysymb file You can also tell it to use /tmp/math.record for the system record file, where it puts logs of sessions. After this math.install will continue on to unpacking things and placing everything where it should go.

The Mathematica Notebook feature is included separately, as the X Front End, and you have to install it separately. To get the X Front End stuff correctly installed, cd into the /usr/local/Mathematica/FrontEnd directory and executed the ./xfe.install shell script. You'll have to tell it where to put things, but you don't have to create any directories because it uses all the same directories that had been created for math.install. When it finished, there should be a new shell script in /usr/local/Mathematica/bin called "mathematica".

Lastly, you need to modify each of the shell scripts that Mathematica has installed. At the beginning of every shell script in /usr/local/Mathematica/bin add the following line: XKEYSYMDB=/usr/local/Mathematica/lib/X11/XKeysymDB; export XKEYSYMDB This tells Mathematica were to find it's own version of the key mapping file XKeysymDB. Without this you will get pages of error messages about missing key mappings. On FreeBSD-stable you need to add the following as well: RESOLV_HOST_CONF=/compat/linux/etc/host.conf; export RESOLV_HOST_CONF This tells Mathematica to use the linux version of host.conf. This file has a different syntax from FreeBSD's host.conf, so you'll get an error message about /etc/host.conf if you leave this out.

You might want to also modify your /etc/manpath.config file to read the new man directory, and you may need to edit your ~/.cshrc file to add /usr/local/Mathematica/bin to your path.

That's about all it takes, With this you should be able to type "mathematica" and get a really slick looking Mathematica Notebook screen up. Mathematica has included the Motif user interfaces, but it's compiled in statically, so you don't need the Motif libraries. Good luck doing this yourself! Bugs

The Notebook front end is known to hang sometimes when reading notebook files with an error messages similar to: File .../Untitled-1.mb appears to be broken for OMPR.257.0 We haven't found the cause for this, but it only affects the Notebook's X window front end, not the mathematica engine itself. So the command line interface invoked by 'math' is unaffected by this bug. Acknowledgments

A well-deserved thanks should go to &a.sos; and &a.peter; who made linux emulation what it is today, and Michael Smith who drove these two guys like dogs to get it to the point where it runs Linux binaries better than linux! :-) diff --git a/handbook/porting.sgml b/handbook/porting.sgml index 41be861cb5..261ea89618 100644 --- a/handbook/porting.sgml +++ b/handbook/porting.sgml @@ -1,1105 +1,1105 @@ - + Porting an existing piece of free software

Contributed by &a.jkh;, &a.gpalmer; and &a.asami;.19 August 1995.

The porting of freely available software, while perhaps not as gratifying as developing your own from scratch, is still a vital part of FreeBSD's growth and of great usefulness to those who would not otherwise know where to turn for it. All ported software is organized into a carefully organized hierarchy know as ``the ports collection''. The collection enables a new user to get a quick and complete overview of what is available for FreeBSD in an easy-to-compile form. It also saves considerable space by not actually containing the the majority of the sources being ported, but merely those differences required for running under FreeBSD.

What follows are some guidelines for creating a new port for FreeBSD 2.x . The ${..} variable names you will see in this document all refer to various user-overrideable defaults used (and documented) by /usr/share/mk/bsd.port.mk. Please refer to that file for more details on the inner workings of the ports collection. Before Starting the Port

Note: Only a fraction of the overrideable variables are mentioned in this document. Most (if not all) are documented at the start of the bsd.port.mk file which can be found in /usr/share/mk. This file uses a non-standard tab setting. Emacs should recognize the setting on loading the file. vi or ex can be set to using the correct value by typing `:set tabstop=4' once the file has been loaded.

You may come across code that needs modifications or conditional compilation based upon what version of UNIX it is running under. If you need to make such changes to the code for conditional compilation, make sure you make the changes as general as possible so that we can back-port code to FreeBSD 1.x systems and cross-port to other BSD systems such as 4.4BSD from CSRG, BSD/386, 386BSD and NetBSD.

The preferred way to tell 4.3BSD/Reno and newer versions of the BSD code apart is by using the `BSD' macro defined in <sys/param.h>. Hopefully that file is already included; if not, add the code: #ifdef _HAVE_PARAM_H #include #endif to the proper place in the .c file and add -D_HAVE_PARAM_H to the CFLAGS in the Makefile. Then, you may use: #if (defined(BSD) && (BSD >= 199103)) to detect if the code is being compiled on a 4.3 Net2 code base or newer (e.g. FreeBSD 1.x, 4.3/Reno, NetBSD 0.9, 386BSD, BSD/386 1.1 and below). Use: #if (defined(BSD) && (BSD >= 199306)) to detect if the code is being compiled on a 4.4 code base or newer (e.g. FreeBSD 2.x, 4.4, NetBSD 1.0, BSD/386 2.0 or above).

Use sparingly: __FreeBSD__ is defined in all versions of FreeBSD. Use it if the change you are making ONLY affects FreeBSD. Porting gotchas like the use of sys_errlist[] vs strerror() are Berkeleyisms, not FreeBSD changes. In FreeBSD 2.x, __FreeBSD__ is defined to be 2. In earlier versions, it is 1. If you need to tell the difference between a FreeBSD 1.x system and a FreeBSD 2.x system, usually the right answer is to use the BSD macros described above. If there actually is a FreeBSD specific change (such as special shared library options when using `ld') then it is OK to use __FreeBSD__ and `#if __FreeBSD__ > 1' to detect a FreeBSD 2.x system. If you need more granularity in detecting FreeBSD systems since 2.0-RELEASE you can use the following: #if __FreeBSD__ >= 2 #include # if __FreeBSD_version >= 199504 /* 2.0.5+ release specific code here */ # endif #endif __FreeBSD_version values: 2.0-RELEASE: 199411 2.1-current's: 199501, 199503 2.0.5-RELEASE: 199504 2.1.0-RELEASE: 199511 2.2-current before 2.1: 199508 2.2-current as 10 Jan 1996: 199512 (will certainly be bumped) The pattern is the year followed by the month.

In the dozens of ports that have been done, there have only been one or two cases where __FreeBSD__ should have been used. Just because an earlier port screwed up and used it in the wrong place does not mean you should do so too. Quick Porting

This section tells you how to do a quick port. In many cases, it is not enough, but we will see.

First, get the original tarball and put it into ${DISTDIR}, which defaults to /usr/ports/distfiles.

Note: The following assumes that the software compiled out-of-the-box, i.e., there was absolutely no change required for the port to work on your FreeBSD box. If you needed to change something, you will have to refer to the next section too. Writing the Makefile

The minimal Makefile would look something like this: # New ports collection makefile for: oneko # Version required: 1.1b # Date created: 5 December 1994 # Whom: asami # - # $Id: porting.sgml,v 1.20 1996-05-16 23:18:08 mpp Exp $ + # $Id: porting.sgml,v 1.21 1996-05-24 19:33:33 jfieber Exp $ # DISTNAME= oneko-1.1b CATEGORIES+= games MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/ MAINTAINER= asami@FreeBSD.ORG USE_IMAKE= yes .include

See if you can figure it out. Do not worry about the contents of the $Id$ line, it will be filled in automatically by CVS when the port is imported to our main ports tree. Writing the description files

There are three required description files that are required for any port, whether they actually package or not. They are COMMENT, DESCR, and PLIST, and reside in the pkg subdirectory. COMMENT

This is the one-line description of the port. It is recommended to not have the name of the package at the beginning, as in: A cat chasing a mouse all over the screen DESCR

This is a longer description of the port. One to a few paragraphs concisely explaining what the port does is sufficient. Note: This is not a manual nor an in-depth description on how to use or compile the port. In particular, please do not just copy the README file here, unless, of course, it is a concise description of the port.

It is recommended that you sign the name at the end of this file, as in: This is a port of oneko, in which a cat chases a poor mouse all over the screen. : (etc.) - Satoshi asami@cs.berkeley.edu PLIST

This file lists all the files installed by the port. It is also called the `packing list' because the package is generated by packing the files listed here. The pathnames are relative to the installation prefix (usually /usr/local or /usr/X11R6).

Here is a small example: bin/oneko man/man1/oneko.1.gz lib/X11/app-defaults/Oneko lib/X11/oneko/cat1.xpm lib/X11/oneko/cat2.xpm lib/X11/oneko/mouse.xpm Creating the checksum file

Just type `make makesum'. The ports make rules will automatically generate the file files/md5. Testing the port

You should make sure that the port rules do exactly what you want it to do, including packaging up the port. Try doing `make install', `make package' and then `pkg_delete -d <pkgname>' and see if all the files are correctly deleted. Then do a `pkg_add <pkgname>.tgz' and see if everything re-appears and works correctly. Submitting the port

Now that you are happy with your port, the only thing remaining is to put it in the main FreeBSD ports tree and make everybody else happy about it too. To accomplish this, pack the necessary files (everything described in this section -- in particular do not include the original source tarball or the `work' subdirectory) into a .tar.gz file, stick it in the directory ftp://ftp.FreeBSD.ORG/pub/FreeBSD/incoming/ and send mail to the &a.ports;. We will take a look, get back to you if necessary, and put it in the tree. Your name will also appear in the list of `Additional FreeBSD contributors' on the FreeBSD Handbook and other files. Isn't that great?!? :) Slow Porting

Ok, so it was not that simple, and the port required some modifications to get it to work. In this section, we will explain, step by step, how to modify it to get it to work with the ports paradigm. How things work

First, this is the sequence of events which occurs when the user first types `make' in your port's directory, and you may find that having bsd.port.mk in another window while you read this really helps to understand it.

But do not worry if you do not really understand what bsd.port.mk is doing, not many people do... :> The fetch target is run. The fetch target is responsible for making sure that the tarball exists locally in ${DISTDIR}. If fetch cannot find the required files in ${DISTDIR} it will look up the ftp-URL ${MASTER_SITES}, which is set in the Makefile. It will then attempt to fetch the named distribution file with ${NCFTP}, assuming that the requesting site has direct access to the Internet. If that succeeds, it will save the file in ${DISTDIR} for future use and proceed. The extract target is run. It looks for your ports' distribution file in ${DISTDIR} (typically a gzip'd tarball) and unpacks it into a temporary subdirectory specified by ${WRKDIR} (defaults to work). The patch target is run. First, any patches defined in ${PATCHFILES} are applied. Second, if any patches are found in ${PATCHDIR} (defaults to the patches subdirectory), they are applied at this time in alphabetical order. The configure target is run. This can do any one of many different things. If it exists, scripts/configure is run. If ${HAS_CONFIGURE} or ${GNU_CONFIGURE} is set, ${WRKSRC}/configure is run. If ${USE_IMAKE} is set, ${XMKMF} (default: `xmkmf -a') is run. The build target is run. This is responsible for descending into the ports' private working directory (${WRKSRC}) and building it. If ${USE_GMAKE} is set, GNU make will be used, otherwise the system make will be used.

The above are the default actions. In addition, you can define targets `pre-<something>' or `post-<something>', or put scripts with those names, in the scripts subdirectory, and they will be run before or after the default actions are done.

For example, if you have a post-extract target defined in your Makefile, and a file pre-build in the scripts subdirectory, the post-extract target will be called after the regular extraction actions, and the pre-build script will be executed before the default build rules are done. It is recommended that you use Makefile targets if possible, because it will be easier for someone to figure out what kind of non-default action the port requires.

The default actions are done by the bsd.port.mk targets `do-<something>'. For example, the commands to extract a port are in the target `do-extract'. If you are not happy with the default target, and you cannot fix it by redefining the `do-<something>' target in your Makefile.

Note that the `main' targets (e.g., extract, configure, etc.) do nothing more than make sure all the stages up to that one is completed and call the real targets or scripts, and they are not intended to be changed. If you want to fix the extraction, fix do-extract, but never ever touch extract!

Now that you understand what goes on when the user types `make', let us go through the recommended steps to create the perfect port. Getting the original sources

Get the original sources (normally) as a compressed tarball (<foo>.tar.gz or <foo>.tar.Z) and copy it into ${DISTDIR}. Always use mainstream sources when and where you can.

If you cannot find a ftp site that is well-connected to the net, or can only find sites that have irritatingly non-standard formats, we can `house' it ourselves by putting it on ftp://freefall.FreeBSD.ORG/pub/FreeBSD/LOCAL_PORTS/ as the last resort. Send mail to the &a.ports if you are not sure what to do.

If your port requires some additional `patches' that are available on the Internet, fetch them too and put them in ${DISTDIR}. Do not worry if they come from site other than where you got the the main source tarball, we have a way to handle these situations (see the description of ${PATCHFILES} below). Modifying the port

Unpack a copy of the tarball in a private directory and make whatever changes are necessary to get the port to compile properly under the current version of FreeBSD. Keep careful track of everything you do, as you will be automating the process shortly. Everything, including the deletion, addition or modification of files should be doable using an automated script or patch file when your port is finished.

If your port requires significant user interaction/customization to compile or install, you should take a look at one of Larry Wall's classic Configure scripts and perhaps do something similar yourself. The goal of the new ports collection is to make each port as `plug-and-play' as possible for the end-user while using a minimum of disk space. Patching

In the preparation of the port, files that have been added or changed can be picked up with a recursive diff for later feeding to patch. This is the easiest kind of change to make as it does not involve any mucking around with configuration files. Each set of patches you wish to apply should be collected into a file named `patch-<xx>' where <xx> denotes the sequence in which the patches will be applied -- these are done in alphabetical order, thus `aa' first, `ab' second and so on. These files should be stored in ${PATCHDIR}, from where they will be automatically applied. All patches should be relative to ${WRKSRC} (generally the directory your port's tarball unpacks itself into, that being where the make is done). To make fixes and upgrades easier you should avoid having more than one patch fix the same file (e.g., patch-aa and patch-ab both changing ${WRKSRC}/foobar.c). Configuring

Include any additional customization commands to your configure script and save it in the `scripts' subdirectory. As mentioned above, you can also do this as Makefile targets and/or scripts with the name pre-configure or post-configure. Handling user input

If your port requires user input to build, configure or install, then set IS_INTERACTIVE in your Makefile. This will allow `overnight builds' to skip your port if the user sets the variable BATCH in his environment (and if the user sets the variable INTERACTIVE, then only those ports requiring interaction are built). Configuring the Makefile

Configuring the Makefile is pretty simple, and again we suggest that you look at existing examples before starting. Consider the following problems in sequence as you design your new Makefile: The original source

Does it live in ${DISTDIR} as a standard gzip'd tarball? If so, you can go on to the next step. If not, you should look at overriding any of the ${EXTRACT_CMD}, ${EXTRACT_BEFORE_ARGS}, ${EXTRACT_AFTER_ARGS}, ${EXTRACT_SUFX}, or ${DISTFILE} variables, depending on how alien a format your port's distribution file is. (The most common case is `EXTRACT_SUFX=.tar.Z', when the tarball is condensed by regular compress, not gzip.)

In the worst case, you can simply create your own `do-extract' target to override the default, though this should be rarely, if ever, necessary. DISTNAME

You should set ${DISTNAME} to be the base name of your port. The default rules expect the distribution file list (${DISTFILES}) to be named ${DISTNAME}${EXTRACT_SUFX} by default which, if it is a normal tarball, is going to be something like: foozolix-1.0.tar.gz for a setting of `DISTNAME=foozolix-1.0'. The default rules also expect the tarball(s) to extract into a subdirectory called work/${DISTNAME}, e.g. work/foozolix-1.0/ All this behavior can be overridden, of course, it simply represents the most common time-saving defaults. For a port requiring multiple distribution files, simply set ${DISTFILES} explicitly. If only a subset of ${DISTFILES} are actual extractable archives, then set them up in ${EXTRACT_ONLY}, which will override the ${DISTFILES} list when it comes to extraction, and the rest will be just left in ${DISTDIR} for later use. CATEGORIES

When a package is created, it is put under /usr/ports/packages/All and links are made from one or more subdirectories of /usr/ports/packages. The names of these subdirectories are specified by the variable ${CATEGORIES}. It is intended to make life easier for the user when he is wading through the pile of packages on the ftp site or the CD-ROM. Please take a look at the existing categories (some of them have different names from subdirectories of /usr/ports) and pick the ones that are suitable for your port. If your port truly belongs to something that is different from all the existing ones, you can even create a new category name. MASTER_SITES

If you have a ftp-URL pointing at the the original tarball, record the directory containing the tarball in ${MASTER_SITES}. This will provide a backup site, as well as a direct pointer to the original source location. Do not forget the trailing slash (/)!

The make macros will try to use this specification for grabbing the distribution file with ${NCFTP} if they cannot find it already on the system.

It is recommended that you put multiple sites on this list, preferably from different continents. This will safeguard against wide-area network problems, and we are even planning to add support for automatically determining the closest master site and fetching from there! PATCHFILES

If your port requires some additional patches that are available by ftp, set ${PATCHFILES} to the names of the files and ${PATCH_SITES} to the URL of the directory that contains them (the format is the same as ${MASTER_SITES}).

If the patch is not relative to the top of the source tree (i.e., ${WKRSRC}) because it contains some extra pathnames, set ${PATCH_DIST_STRIP} accordingly. For instance, if all the pathnames in the patch has an extra `foozolix-1.0/' in front of the filenames, then set `PATCH_DIST_STRIP=-p1'.

Do not worry if the patches are compressed, they will be decompressed automatically if the filenames end with `.gz' or `.Z'. MAINTAINER

Set your mail-address here. Please. :) Dependencies

Many ports depend on other ports. There are five variables that you can use to ensure that all the required bits will be on the user's machine. LIB_DEPENDS

This variable specifies the shared libraries this port depends on. It is a list of `lib:dir' pairs where lib is the name of the shared library, and dir is the directory in which to find it in case it is not available. For example, LIB_DEPENDS= tcl\\.7\\.:${PORTSDIR}/lang/tcl will check for a shared tcl library with major version 7, and descend into the lang/tcl subdirectory of your ports tree to build and install it if it is not found. Note that the lib part is just an argument given to `ldconfig -r | grep', so periods should be escaped by two backslashes like in the example above. RUN_DEPENDS

This variable specifies executables this port depends on during run-time. It is a list of `exec:dir' pairs where exec is the name of the executable, and dir is the directory in which to find it in case it is not available. For example, RUN_DEPENDS= wish:${PORTSDIR}/x11/tk will check for an executable called `wish', and descend into the x11/tk subdirectory of your ports tree to build and install it if it is not found. The dependency is checked from within the install target. Also, the name of the dependency is put in to the package so that pkg_add will automatically install it if it is not on the user's system. BUILD_DEPENDS

This variable specifies executables this port requires to build. Like RUN_DEPENDS, it is a list of `exec:dir' pairs. For example, BUILD_DEPENDS= unzip:${PORTSDIR}/archivers/unzip will check for an executable called `unzip', and descend into the archivers/unzip subdirectory of your ports tree to build and install it if it is not found. Note that `build' here means everything from extracting to compilation. The dependency is checked from within the extract target. FETCH_DEPENDS

This variable specifies executables this port requires to fetch. Like the previous two, it is a list of `exec:dir' pairs. For example, FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 will check for an executable called `ncftp2', and descend into the net/ncftp2 subdirectory of your ports tree to build and install it if it is not found. The dependency is checked from within the fetch target. DEPENDS

If there is a dependency that does not fall into either of the above four categories, or your port requires to have the source of the other port extracted (i.e., having them installed is not enough), then use this variable. This is just a list of directories, as there is nothing to check, unlike the previous two. Building mechanisms

If your package uses GNU make, set `USE_GMAKE=yes'. If your package uses GNU configure, set `GNU_CONFIGURE=yes'. If you want to override the default GNU configure arguments from `--prefix=${PREFIX}' to something else, set those arguments in ${CONFIGURE_ARGS}.

If your package uses imake (e.g. is an X application that has an Imakefile), then set `USE_IMAKE=yes'. This will cause the configure stage to automatically do an xmkmf -a. If the `-a' flag is a problem for your port, set `XMKMF=xmkmf'.

If your port's source Makefile has something else than `all' as the main build target, set ${ALL_TARGET} accordingly. Same goes for `install' and ${INSTALL_TARGET}. NO_INSTALL_MANPAGES

If the port uses imake but does not understand the `install.man' target, `NO_INSTALL_MANPAGES=yes' should be set. In addition, the author of the original port should be shot. Licensing Problems

Some software packages have restrictive licenses or are in violation to the law (PKP's patent on public key crypto, ITAR (export of crypto software) to name just two of them). What we can do with them vary a lot, depending on the exact wordings of the respective licenses.

Note that it is your responsibility as a porter to read the licensing terms of the software and make sure that the FreeBSD project will not be held accountable of violating them by redistributing the source or compiled binaries either via ftp or CD-ROM. If in doubt, please contact the &a.ports;.

We usually get around this problem by setting ${NO_PACKAGE} in the Makefile, and not putting the distfile up for ftp. However, for most cases, you should at least be able to make a port, so do not let the license scare you away!

Note: The GNU General Public License (GPL), both version 1 and 2, should not be a problem for ports.

Note: If you are a committer, make sure you update the ports/LEGAL file too. * Upgrading

This section is still under construction, sorry. Do's and Dont's

Here is a list of common do's and dont's that you encounter during the porting process. WRKDIR

Do not leave anything valuable lying around in the `work' subdirectory, `make clean' will nuke it completely! If you need auxiliary files that are not scripts or patches, put them in the subdirectory `files' and use the post-extract target to copy them to the `work' subdirectory. Package information

Do install package information, i.e., the three files in pkg. Note that these files are not used only for packaging anymore, and are mandatory now, even if ${NO_PACKAGE} is set. Compress manpages, strip binaries

Do compress manpages and strip binaries. If the original source already does that, fine; otherwise, you can add a post-install rule to do it yourself. Make sure that you check the variable NOMANCOMPRESS that the user can set in /etc/make.conf to disable man page compression. Here is an example: post-install: strip ${PREFIX}/bin/xdl .if !defined(NOMANCOMPRESS) gzip -9nf ${PREFIX}/man/man1/xdl.1 .endif

Use the file command on the installed executable to check whether the binary is stripped or not. If it does not say `not stripped', it is stripped. Install additional documentation

If your software has some documentation other than the standard man and info pages that you think is useful for the user, install it under ${PREFIX}/share/doc. This can be done, like the previous item, in the post-install target.

Create a new directory for your port. The directory name should reflect what the port is. This usually means ${PKGNAME} minus the version part. However, if you think the user might want different versions of the port to be installed at the same time (e.g., tcl/tk), you can use the whole ${PKGNAME}.

Make the installation dependent to the variable NOPORTDOCS so that users can disable it in /etc/make.conf, like this: post-install: .if !defined(NOPORTDOCS) mkdir -p ${PREFIX}/share/doc/xv cp ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv .endif

Do not forget to add them to pkg/PLIST too! (Do not worry about NOPORTDOCS here; there is currently no way for the packages to read variables from /etc/make.conf.) DIST_SUBDIR

Do not let your port clutter /usr/ports/distfiles. If your port requires a lot of files (including patchfiles) to be fetched, or contains a file that has a name that might conflict with other ports (e.g., `Makefile'), set ${DIST_SUBDIR} to the name of the port (${PKGNAME} without the version part should work fine). This will change ${DISTDIR} from the default /usr/ports/distfiles to /usr/ports/distfiles/${DIST_SUBDIR}, and in effect puts everything that is required for your port into that subdirectory.

It will also look at the subdirectory with the same name on the backup master site at ftp.freebsd.org. (Setting ${DISTDIR} explicitly in your Makefile will not accomplish this, so please use ${DIST_SUBDIR}.)

Note this does not affect the ${MASTER_SITES} you define in your Makefile. Custom utilities

Do not rely on custom utilities in your local configure script or anything -- they may not be there on the user's system! If you really need something else to be installed before you can work, detect this from your configure script, print a helpful message and exit with a non-zero status! At least you will have given the user some idea of what is needed. If the custom utility or package is actually part of the ports tree, this should be dealt by the dependency mechanism of ports.

Actually, if this utility is not part of the ports tree you should probably make a port of this utility (this is how many of the ports made it into the tree!). Depending on something that is not part of the main FreeBSD distribution or the ports tree is a bad idea, and the user should be able to go to any subdirectory of /usr/ports and type `make' and have that port, as well as everything it requires, built automatically. Feedback

Do send applicable changes/patches to the original author/maintainer for inclusion in next release of the code. This will only make your job that much easier for the next release. RCS strings

Do not put RCS strings in patches. CVS will mangle them when we put the files into the ports tree, and when we check them out again, they will come out different and the patch will fail. RCS strings are surrounded by dollar (`$') signs, and typically start with `$Id' or `$RCS'. Recursive diff

Using the recurse (`-r') option to diff to generate patches is fine, but please take a look at the resulting patches to make sure you don't have any unnecessary junk in there. In particular, diffs between two backup files, Makefiles when the port uses imake or GNU configure, etc., are unnecessary and should be deleted. Also, if you had to delete a file, then you can do it in the post-extract target rather than as part of the patch. PREFIX

Do try to make your port install relative to ${PREFIX}. (The value of this variable will be set to ${LOCALBASE} (default /usr/local), unless ${USE_IMAKE} or ${USE_X11} is set, in which case it will be ${X11BASE} (default /usr/X11R6).)

Not hard-coding `/usr/local' or `/usr/X11R6' anywhere in the source will make the port much more flexible and able to cater to the needs of other sites. For X ports that use imake, this is automatic; otherwise, this can often be done by simply replacing the occurrences of `/usr/local' (or `/usr/X11R6' for X ports that do not use imake) in the various scripts/Makefiles in the port to read `${PREFIX}', as this variable is automatically passed down to every stage of the build and install processes.

The variable ${PREFIX} can be reassigned in your Makefile or in the user's environment. However, it is strongly discouraged for individual ports to set this variable explicitly in the Makefiles. (If your port is an X port but does not use imake, set USE_X11=yes; this is quite different from setting PREFIX=/usr/X11R6.)

Also, refer to programs/files from other ports with the variables mentioned above, not explicit pathnames. For instance, if your port requires a macro PAGER to be the full pathname of less, use the compiler flag: - `-DPAGER=\"${PREFIX}/bin/less\"' (or - `-DPAGER=\"${LOCALBASE}/bin/less\"' if this is an - X port), instead of `-DPAGER=\"/usr/local/bin/less\"'. + -DPAGER=\"${PREFIX}/bin/less\" or + -DPAGER=\"${LOCALBASE}/bin/less\" if this is an + X port, instead of -DPAGER=\"/usr/local/bin/less\". This way it will have a better chance of working if the system administrator has moved the whole `/usr/local' tree somewhere else. Subdirectories

Try to let the port put things in the right subdirectories of ${PREFIX}. Some ports lump everything and put it in the subdirectory with the port's name, which is incorrect. Also, many ports put everything except binaries, header files and manual pages in the a subdirectory of `lib', which does not bode well with the BSD paradigm. Many of the files should me moved to one of the following: `etc' (setup/configuration files), `libexec' (executables started internally), `sbin' (executables for superusers/managers) or `share' (architecture independent files). See hier(7) for details, the rule governing /usr pretty much applies to /usr/local too. ldconfig

If your port installs a shared library, add a post-install target to your Makefile that runs `/sbin/ldconfig -m' on the directory where the new library is installed (usually ${PREFIX}/lib) to register it into the shared library cache.

Also, add an @exec line to your pkg/PLIST file so that a user who installed the package can start using the shared library immediately. This line should immediately follow the line for the shared library itself, as in: lib/libtcl.so.7.3 @exec /sbin/ldconfig -m %D/lib

Note: the `-m' option is new since 2.0.5 and 2.1.0-950726-SNAP, so do not be alarmed if it does not work on your machine.

Never, ever, ever add a line that says `ldconfig' without any arguments to your Makefile or pkg/PLIST. This will reset the shared library cache to the contents of /usr/lib only, and will royally screw up the user's machine ("Help, xinit does not run anymore after I install this port!"). Anybody who does this will be shot and cut into 65,536 pieces by a rusty knife and have his liver chopped out by a bunch of crows and will eternally rot to death in the deepest bowels of hell (not necessarily in that order).... If you are stuck....

Do look at existing examples and the bsd.port.mk file before asking us questions! ;)

Do ask us questions if you have any trouble! Do not just beat your head against a wall! :) A Sample Makefile

Here is a sample Makefile that you can use to create a new port. Make sure you remove all the extra comments (ones between brackets)!

It is recommended that you follow this format (ordering of variables, etc.). Not all of the existing Makefiles are in this format (mostly old ones), but we are trying to uniformize how they look. This format is designed so that the most important information is easy to locate. [the header...just to make it easier for us to identify the ports] # New ports collection makefile for: xdvi # Version required: 2.2 [things like "1.5alpha" are fine here too] # Date created: 26 May 1995 [this is the person who did the original port to FreeBSD, in particular, the person who wrote this Makefile] # Whom: Satoshi Asami # - # $Id: porting.sgml,v 1.20 1996-05-16 23:18:08 mpp Exp $ + # $Id: porting.sgml,v 1.21 1996-05-24 19:33:33 jfieber Exp $ [ ^^^^ do not worry about this...it will be automatically filled in by CVS when it is committed to our repository] # [section to describe the package itself and main ftp site - DISTNAME is always first, followed by PKGNAME (if necessary), CATEGORIES, and then MASTER_SITES, and optionally EXTRACT_SUFX or DISTFILES] DISTNAME= xdvi PKGNAME= xdvi-pl18 CATEGORIES+= printing [do not forget the trailing slash ("/")!] MASTER_SITES= ftp://crl.dec.com/pub/X11/contrib/applications/ [set this if the source is not in the standard ".tar.gz" form] EXTRACT_SUFX= .tar.Z [section for distributed patches -- can be empty] PATCH_SITES= ftp://ftp.sra.co.jp/pub/X11/japanese/ PATCHFILES= xdvi-18.patch1.gz xdvi-18.patch2.gz [maintainer; *mandatory*! This is the person (preferably with commit privileges) who a user can contact for questions and bug reports - this person should be the porter or someone who can forward questions to the original porter reasonably promptly. If you really do not want to have your address here, set it to "ports@FreeBSD.ORG".] MAINTAINER= asami@FreeBSD.ORG [dependencies -- can be empty] RUN_DEPENDS= gs:${PORTSDIR}/print/ghostscript LIB_DEPENDS= Xpm\\.4\\.:${PORTSDIR}/graphics/xpm [this section is for other standard bsd.port.mk variables that do not belong to any of the above] [If it extracts to a directory other than ${DISTNAME}...] WRKSRC= ${WRKDIR}/xdvi-new [If it asks questions during configure, build, install...] IS_INTERACTIVE= yes [If it requires "configure" in the distributed source directory to be run...] HAS_CONFIGURE= yes [If it requires GNU make, not /usr/bin/make, to build...] USE_GMAKE= yes [If it is an X application and requires "xmkmf -a" to be run...] USE_IMAKE= yes [et cetera.] [non-standard variables to be used in the rules below] MY_FAVORITE_RESPONSE= "yeah, right" [then the special rules, in the order they are called] pre-fetch: i go fetch something, yeah post-patch: i need to do something after patch, great pre-install: and then some more stuff before installing, wow [and then the epilogue] .include Package Names

The following are the conventions you should follow in naming your packages. This is to have our package directory easy to scan, as there are already lots and lots of packages and users are going to turn away if they hurt their eyes!

If your ${DISTNAME} does not look like `<name>-<version.string.numbers>', set ${PKGNAME} to something in that format. The `<name>' part should be all lowercases, except for a really large package (with lots of programs in it). Things like XFree86 (yes there really is a package of it, check it out) and ImageMagick fall into this category. Otherwise, convert the name (or at least the first letter) to lowercase. If the software in question really is called that way, you can have numbers, hyphens and underscores in the name too. The version string should be a period-separated list of integers and single lowercase alphabets. The only exception is the string `pl' (meaning `patchlevel'), which can be used only when there are no major and minor version numbers in the software.

Here are some (real) examples on how to convert a ${DISTNAME} into a suitable ${PKGNAME}: DISTNAME PKGNAME Reason mule-2.2.2 mule-2.2.2 no prob at all XFree86-3.1.2 XFree86-3.1.2 ditto EmiClock-1.0.2 emiclock-1.0.2 no uppercase names for single programs gmod1.4 gmod-1.4 need hyphen after `' xmris.4.02 xmris-4.02 ditto rdist-1.3alpha rdist-1.3a no strings like `alpha' allowed es-0.9-beta1 es-0.9b1 ditto v3.3beta021.src jpeg-5a what the heck was that anyway? ;) tvtwm tvtwm-pl11 version string always required piewm piewm-1.0 ditto xvgr-2.10pl1 xvgr-2.10.1 `pl' allowed only when no maj/minor numbers

If there is absolutely no trace of version information in the original source and it is unlikely that the original author will ever release another version, just set the version string to `1.0' (like the piewm example above). Otherwise, ask the original author or use the date string (`yy.mm.dd') as the version. That is It, Folks!

Boy, this sure was a long tutorial, wasn't it? Thanks for following us to here, really.

Well, now that you know how to do a port, let us go at it and convert everything in the world into ports! That is the easiest way to start contributing to the FreeBSD Project! :)