Go to the first, previous, next, last section, table of contents.

# Porting with `configure`

This section explains how to add programs, host and target configuration names, and site-specific information to Cygnus `configure`.

- Programs: Adding configure to new programs
- Hosts and targets: Adding hosts and targets
- Sites: Adding site info

## Adding `configure` to new programs

If you are writing a new program, you probably shouldn't worry about porting or configuration issues until it is running reasonably on some host. Then refer back to this section.

If your program currently has a `configure` script that meets the GNU standards (see section `How Configuration Should Work' in GNU Coding Standards, please do not add Cygnus `configure`. It should be possible to add this program without change to a Cygnus `configure` style source tree.

If the program is not target dependent, please consider using `autoconf` instead of Cygnus `configure`. `autoconf` is available from the Free Software Foundation; it is a program which generates an executable shell script called ``configure'` by automatically finding information on the system to be configured on and embedding this information in the shell script. ``configure'` scripts generated by `autoconf` require no arguments, and accept the same options as Cygnus `configure`. For detailed instructions on using `autoconf`, see section `How to organize and produce Autoconf scripts' in Autoconf.

To add Cygnus `configure` to an existing program, do the following:

@bullet{Make sure the ``Makefile'` conforms to the GNU standard}
  The coding standard for writing a GNU ``Makefile'` is described in section `Makefile Conventions' in GNU Coding Standards. For technical information on writing a ``Makefile'`, see section `Writing Makefiles' in GNU Make.
@bullet{Add Cygnus extensions to the ``Makefile'`}
  These are described in section Extensions to the GNU coding standards.
@bullet{Collect package specific definitions in a single file}
  Many packages are best configured using a common ``Makefile'` fragment which is included by all of the makefiles in the different directories of the package. In order to accomplish this, set the variable ``package_makefile_fragment'` to the name of the file. It will be inserted into the final ``Makefile'` before the target-specific fragment.
@bullet{Move host support from ``Makefile'` to fragments}
  This usually involves finding sections of the ``Makefile'` that say things like "uncomment these lines for host hosttype" and moving them to a new file called ``./config/mh-hosttype'`. For more information, see section Adding hosts and targets.
@bullet{Choose defaults}
  If the program has compile-time options that determine the way the program should behave, choose reasonable defaults and make these ``Makefile'` variables. Be sure the variables are assigned their default values before the ``####'` line so that site-specific ``Makefile'` fragments can override them (see section Extensions to the GNU coding standards).
@bullet{Locate configuration files}
  If there is configuration information in header files or source files, separate it in such a way that the files have generic names. Then move the specific instances of those files into the ``./config/'` subdirectory.
@bullet{Separate host and target information}
  Some programs already have this information separated. If yours does not, you will need to separate these two kinds of configuration information. Host specific information is the information needed to compile the program. Target specific information is information on the format of data files that the program will read or write. This information should live in separate files in the ``./config/'` subdirectory with names that reflect the configuration for which they are intended. At this point you might skip this step and simply move on. If you do, you should end up with a program that can be configured only to build native tools, that is, tools for which the host system is also the target system. Later, you could attempt to build a cross tool and separate out the target-specific information by figuring out what went wrong. This is often simpler than combing through all of the source code.
@bullet{Write `configure.in`}
  Usually this involves writing shell script fragments to map from canonical configuration names into the names of the configuration files. These files will then be linked at configure time from the specific instances of those files in ``./config'` to files in the build directory with more generic names. (See also section Build directories.) The format of ``configure.in'` is described in section The `configure.in` input file.
@bullet{Rename ``Makefile'` to ``Makefile.in'`}

At this point you should have a program that can be configured using Cygnus `configure`.

## Adding hosts and targets

To add a host or target to a program that already uses Cygnus `configure`, do the following.

- Make sure the new configuration name is represented in ``config.sub'`. If not, add it. For more details, see the comments in the shell script ``config.sub'`.
- If you are adding a host configuration, look in ``configure.in'`, in the per-host section. Make sure that your configuration name is represented in the mapping from host configuration names to configuration files. If not, add it. Also see section The `configure.in` input file.
- If you are adding a target configuration, look in ``configure.in'`, in the per-target section. Make sure that your configuration name is represented in the mapping from target configuration names to configuration files. If not, add it. Also see section The `configure.in` input file.
- Look in ``configure.in'` for the variables ``files'`, ``links'`, ``host_makefile_frag'`, and ``target_makefile_frag'`. The values assigned to these variables are the names of the configuration files, (relative to ``srcdir'`) that the program uses. Make sure that copies of the files exist for your host. If not, create them. See also section Variables available to `configure.in`.

This should be enough to `configure` for a new host or target configuration name. Getting the program to compile and run properly represents the hardest work of any port.

## Adding site info

If some of the ``Makefile'` defaults are not right for your site, you can build site-specific ``Makefile'` fragments. To do this, do the following.

- Choose a name for your site. It must currently be less than eleven characters.
- If the program source does not have a ``./config/'` subdirectory, create it.
- Create a file called ``./config/ms-site'` where site is the name of your site. In it, set whatever ``Makefile'` variables you need to override to match your site's conventions.
- Configure the program with:

      configure ... --site=site

Go to the first, previous, next, last section, table of contents.