| This is configure.info, produced by makeinfo version 4.2 from |
| ./configure.texi. |
| |
| INFO-DIR-SECTION GNU admin |
| START-INFO-DIR-ENTRY |
| * configure: (configure). The GNU configure and build system |
| END-INFO-DIR-ENTRY |
| |
| This file documents the GNU configure and build system. |
| |
| Copyright (C) 1998 Cygnus Solutions. |
| |
| Permission is granted to make and distribute verbatim copies of this |
| manual provided the copyright notice and this permission notice are |
| preserved on all copies. |
| |
| Permission is granted to copy and distribute modified versions of |
| this manual under the conditions for verbatim copying, provided that |
| the entire resulting derived work is distributed under the terms of a |
| permission notice identical to this one. |
| |
| Permission is granted to copy and distribute translations of this |
| manual into another language, under the above conditions for modified |
| versions, except that this permission notice may be stated in a |
| translation approved by the Foundation. |
| |
| |
| File: configure.info, Node: Configuration Name Definition, Next: Using Configuration Names, Up: Configuration Names |
| |
| Configuration Name Definition |
| ============================= |
| |
| This is a string of the form CPU-MANUFACTURER-OPERATING_SYSTEM. In |
| some cases, this is extended to a four part form: |
| CPU-MANUFACTURER-KERNEL-OPERATING_SYSTEM. |
| |
| When using a configuration name in a configure option, it is normally |
| not necessary to specify an entire name. In particular, the |
| MANUFACTURER field is often omitted, leading to strings such as |
| `i386-linux' or `sparc-sunos'. The shell script `config.sub' will |
| translate these shortened strings into the canonical form. autoconf |
| will arrange for `config.sub' to be run automatically when it is needed. |
| |
| The fields of a configuration name are as follows: |
| |
| CPU |
| The type of processor. This is typically something like `i386' or |
| `sparc'. More specific variants are used as well, such as |
| `mipsel' to indicate a little endian MIPS processor. |
| |
| MANUFACTURER |
| A somewhat freeform field which indicates the manufacturer of the |
| system. This is often simply `unknown'. Other common strings are |
| `pc' for an IBM PC compatible system, or the name of a workstation |
| vendor, such as `sun'. |
| |
| OPERATING_SYSTEM |
| The name of the operating system which is run on the system. This |
| will be something like `solaris2.5' or `irix6.3'. There is no |
| particular restriction on the version number, and strings like |
| `aix4.1.4.0' are seen. For an embedded system, which has no |
| operating system, this field normally indicates the type of object |
| file format, such as `elf' or `coff'. |
| |
| KERNEL |
| This is used mainly for GNU/Linux. A typical GNU/Linux |
| configuration name is `i586-pc-linux-gnulibc1'. In this case the |
| kernel, `linux', is separated from the operating system, |
| `gnulibc1'. |
| |
| The shell script `config.guess' will normally print the correct |
| configuration name for the system on which it is run. It does by |
| running `uname' and by examining other characteristics of the system. |
| |
| Because `config.guess' can normally determine the configuration name |
| for a machine, it is normally only necessary to specify a configuration |
| name when building a cross-compiler or when building using a |
| cross-compiler. |
| |
| |
| File: configure.info, Node: Using Configuration Names, Prev: Configuration Name Definition, Up: Configuration Names |
| |
| Using Configuration Names |
| ========================= |
| |
| A configure script will sometimes have to make a decision based on a |
| configuration name. You will need to do this if you have to compile |
| code differently based on something which can not be tested using a |
| standard autoconf feature test. |
| |
| It is normally better to test for particular features, rather than to |
| test for a particular system. This is because as Unix evolves, |
| different systems copy features from one another. Even if you need to |
| determine whether the feature is supported based on a configuration |
| name, you should define a macro which describes the feature, rather than |
| defining a macro which describes the particular system you are on. |
| |
| Testing for a particular system is normally done using a case |
| statement in `configure.in'. The case statement might look something |
| like the following, assuming that `host' is a shell variable holding a |
| canonical configuration name (which will be the case if `configure.in' |
| uses the `AC_CANONICAL_HOST' or `AC_CANONICAL_SYSTEM' macro). |
| |
| case "${host}" in |
| i[3456]86-*-linux-gnu*) do something ;; |
| sparc*-sun-solaris2.[56789]*) do something ;; |
| sparc*-sun-solaris*) do something ;; |
| mips*-*-elf*) do something ;; |
| esac |
| |
| It is particularly important to use `*' after the operating system |
| field, in order to match the version number which will be generated by |
| `config.guess'. |
| |
| In most cases you must be careful to match a range of processor |
| types. For most processor families, a trailing `*' suffices, as in |
| `mips*' above. For the i386 family, something along the lines of |
| `i[3456]86' suffices at present. For the m68k family, you will need |
| something like `m68*'. Of course, if you do not need to match on the |
| processor, it is simpler to just replace the entire field by a `*', as |
| in `*-*-irix*'. |
| |
| |
| File: configure.info, Node: Cross Compilation Tools, Next: Canadian Cross, Prev: Configuration Names, Up: Top |
| |
| Cross Compilation Tools |
| *********************** |
| |
| The GNU configure and build system can be used to build "cross |
| compilation" tools. A cross compilation tool is a tool which runs on |
| one system and produces code which runs on another system. |
| |
| * Menu: |
| |
| * Cross Compilation Concepts:: Cross Compilation Concepts. |
| * Host and Target:: Host and Target. |
| * Using the Host Type:: Using the Host Type. |
| * Specifying the Target:: Specifying the Target. |
| * Using the Target Type:: Using the Target Type. |
| * Cross Tools in the Cygnus Tree:: Cross Tools in the Cygnus Tree |
| |
| |
| File: configure.info, Node: Cross Compilation Concepts, Next: Host and Target, Up: Cross Compilation Tools |
| |
| Cross Compilation Concepts |
| ========================== |
| |
| A compiler which produces programs which run on a different system |
| is a cross compilation compiler, or simply a "cross compiler". |
| Similarly, we speak of cross assemblers, cross linkers, etc. |
| |
| In the normal case, a compiler produces code which runs on the same |
| system as the one on which the compiler runs. When it is necessary to |
| distinguish this case from the cross compilation case, such a compiler |
| is called a "native compiler". Similarly, we speak of native |
| assemblers, etc. |
| |
| Although the debugger is not strictly speaking a compilation tool, |
| it is nevertheless meaningful to speak of a cross debugger: a debugger |
| which is used to debug code which runs on another system. Everything |
| that is said below about configuring cross compilation tools applies to |
| the debugger as well. |
| |
| |
| File: configure.info, Node: Host and Target, Next: Using the Host Type, Prev: Cross Compilation Concepts, Up: Cross Compilation Tools |
| |
| Host and Target |
| =============== |
| |
| When building cross compilation tools, there are two different |
| systems involved: the system on which the tools will run, and the |
| system for which the tools generate code. |
| |
| The system on which the tools will run is called the "host" system. |
| |
| The system for which the tools generate code is called the "target" |
| system. |
| |
| For example, suppose you have a compiler which runs on a GNU/Linux |
| system and generates ELF programs for a MIPS embedded system. In this |
| case the GNU/Linux system is the host, and the MIPS ELF system is the |
| target. Such a compiler could be called a GNU/Linux cross MIPS ELF |
| compiler, or, equivalently, a `i386-linux-gnu' cross `mips-elf' |
| compiler. |
| |
| Naturally, most programs are not cross compilation tools. For those |
| programs, it does not make sense to speak of a target. It only makes |
| sense to speak of a target for tools like `gcc' or the `binutils' which |
| actually produce running code. For example, it does not make sense to |
| speak of the target of a tool like `bison' or `make'. |
| |
| Most cross compilation tools can also serve as native tools. For a |
| native compilation tool, it is still meaningful to speak of a target. |
| For a native tool, the target is the same as the host. For example, for |
| a GNU/Linux native compiler, the host is GNU/Linux, and the target is |
| also GNU/Linux. |
| |
| |
| File: configure.info, Node: Using the Host Type, Next: Specifying the Target, Prev: Host and Target, Up: Cross Compilation Tools |
| |
| Using the Host Type |
| =================== |
| |
| In almost all cases the host system is the system on which you run |
| the `configure' script, and on which you build the tools (for the case |
| when they differ, *note Canadian Cross::). |
| |
| If your configure script needs to know the configuration name of the |
| host system, and the package is not a cross compilation tool and |
| therefore does not have a target, put `AC_CANONICAL_HOST' in |
| `configure.in'. This macro will arrange to define a few shell |
| variables when the `configure' script is run. |
| |
| `host' |
| The canonical configuration name of the host. This will normally |
| be determined by running the `config.guess' shell script, although |
| the user is permitted to override this by using an explicit |
| `--host' option. |
| |
| `host_alias' |
| In the unusual case that the user used an explicit `--host' option, |
| this will be the argument to `--host'. In the normal case, this |
| will be the same as the `host' variable. |
| |
| `host_cpu' |
| `host_vendor' |
| `host_os' |
| The first three parts of the canonical configuration name. |
| |
| The shell variables may be used by putting shell code in |
| `configure.in'. For an example, see *Note Using Configuration Names::. |
| |
| |
| File: configure.info, Node: Specifying the Target, Next: Using the Target Type, Prev: Using the Host Type, Up: Cross Compilation Tools |
| |
| Specifying the Target |
| ===================== |
| |
| By default, the `configure' script will assume that the target is |
| the same as the host. This is the more common case; for example, it |
| leads to a native compiler rather than a cross compiler. |
| |
| If you want to build a cross compilation tool, you must specify the |
| target explicitly by using the `--target' option when you run |
| `configure'. The argument to `--target' is the configuration name of |
| the system for which you wish to generate code. *Note Configuration |
| Names::. |
| |
| For example, to build tools which generate code for a MIPS ELF |
| embedded system, you would use `--target mips-elf'. |
| |
| |
| File: configure.info, Node: Using the Target Type, Next: Cross Tools in the Cygnus Tree, Prev: Specifying the Target, Up: Cross Compilation Tools |
| |
| Using the Target Type |
| ===================== |
| |
| When writing `configure.in' for a cross compilation tool, you will |
| need to use information about the target. To do this, put |
| `AC_CANONICAL_SYSTEM' in `configure.in'. |
| |
| `AC_CANONICAL_SYSTEM' will look for a `--target' option and |
| canonicalize it using the `config.sub' shell script. It will also run |
| `AC_CANONICAL_HOST' (*note Using the Host Type::). |
| |
| The target type will be recorded in the following shell variables. |
| Note that the host versions of these variables will also be defined by |
| `AC_CANONICAL_HOST'. |
| |
| `target' |
| The canonical configuration name of the target. |
| |
| `target_alias' |
| The argument to the `--target' option. If the user did not specify |
| a `--target' option, this will be the same as `host_alias'. |
| |
| `target_cpu' |
| `target_vendor' |
| `target_os' |
| The first three parts of the canonical target configuration name. |
| |
| Note that if `host' and `target' are the same string, you can assume |
| a native configuration. If they are different, you can assume a cross |
| configuration. |
| |
| It is arguably possible for `host' and `target' to represent the |
| same system, but for the strings to not be identical. For example, if |
| `config.guess' returns `sparc-sun-sunos4.1.4', and somebody configures |
| with `--target sparc-sun-sunos4.1', then the slight differences between |
| the two versions of SunOS may be unimportant for your tool. However, |
| in the general case it can be quite difficult to determine whether the |
| differences between two configuration names are significant or not. |
| Therefore, by convention, if the user specifies a `--target' option |
| without specifying a `--host' option, it is assumed that the user wants |
| to configure a cross compilation tool. |
| |
| The variables `target' and `target_alias' should be handled |
| differently. |
| |
| In general, whenever the user may actually see a string, |
| `target_alias' should be used. This includes anything which may appear |
| in the file system, such as a directory name or part of a tool name. |
| It also includes any tool output, unless it is clearly labelled as the |
| canonical target configuration name. This permits the user to use the |
| `--target' option to specify how the tool will appear to the outside |
| world. |
| |
| On the other hand, when checking for characteristics of the target |
| system, `target' should be used. This is because a wide variety of |
| `--target' options may map into the same canonical configuration name. |
| You should not attempt to duplicate the canonicalization done by |
| `config.sub' in your own code. |
| |
| By convention, cross tools are installed with a prefix of the |
| argument used with the `--target' option, also known as `target_alias' |
| (*note Using the Target Type::). If the user does not use the |
| `--target' option, and thus is building a native tool, no prefix is |
| used. |
| |
| For example, if gcc is configured with `--target mips-elf', then the |
| installed binary will be named `mips-elf-gcc'. If gcc is configured |
| without a `--target' option, then the installed binary will be named |
| `gcc'. |
| |
| The autoconf macro `AC_ARG_PROGRAM' will handle this for you. If |
| you are using automake, no more need be done; the programs will |
| automatically be installed with the correct prefixes. Otherwise, see |
| the autoconf documentation for `AC_ARG_PROGRAM'. |
| |
| |
| File: configure.info, Node: Cross Tools in the Cygnus Tree, Prev: Using the Target Type, Up: Cross Compilation Tools |
| |
| Cross Tools in the Cygnus Tree |
| ============================== |
| |
| The Cygnus tree is used for various packages including gdb, the GNU |
| binutils, and egcs. It is also, of course, used for Cygnus releases. |
| |
| In the Cygnus tree, the top level `configure' script uses the old |
| Cygnus configure system, not autoconf. The top level `Makefile.in' is |
| written to build packages based on what is in the source tree, and |
| supports building a large number of tools in a single |
| `configure'/`make' step. |
| |
| The Cygnus tree may be configured with a `--target' option. The |
| `--target' option applies recursively to every subdirectory, and |
| permits building an entire set of cross tools at once. |
| |
| * Menu: |
| |
| * Host and Target Libraries:: Host and Target Libraries. |
| * Target Library Configure Scripts:: Target Library Configure Scripts. |
| * Make Targets in Cygnus Tree:: Make Targets in Cygnus Tree. |
| * Target libiberty:: Target libiberty |
| |
| |
| File: configure.info, Node: Host and Target Libraries, Next: Target Library Configure Scripts, Up: Cross Tools in the Cygnus Tree |
| |
| Host and Target Libraries |
| ------------------------- |
| |
| The Cygnus tree distinguishes host libraries from target libraries. |
| |
| Host libraries are built with the compiler used to build the programs |
| which run on the host, which is called the host compiler. This includes |
| libraries such as `bfd' and `tcl'. These libraries are built with the |
| host compiler, and are linked into programs like the binutils or gcc |
| which run on the host. |
| |
| Target libraries are built with the target compiler. If gcc is |
| present in the source tree, then the target compiler is the gcc that is |
| built using the host compiler. Target libraries are libraries such as |
| `newlib' and `libstdc++'. These libraries are not linked into the host |
| programs, but are instead made available for use with programs built |
| with the target compiler. |
| |
| For the rest of this section, assume that gcc is present in the |
| source tree, so that it will be used to build the target libraries. |
| |
| There is a complication here. The configure process needs to know |
| which compiler you are going to use to build a tool; otherwise, the |
| feature tests will not work correctly. The Cygnus tree handles this by |
| not configuring the target libraries until the target compiler is |
| built. In order to permit everything to build using a single |
| `configure'/`make', the configuration of the target libraries is |
| actually triggered during the make step. |
| |
| When the target libraries are configured, the `--target' option is |
| not used. Instead, the `--host' option is used with the argument of |
| the `--target' option for the overall configuration. If no `--target' |
| option was used for the overall configuration, the `--host' option will |
| be passed with the output of the `config.guess' shell script. Any |
| `--build' option is passed down unchanged. |
| |
| This translation of configuration options is done because since the |
| target libraries are compiled with the target compiler, they are being |
| built in order to run on the target of the overall configuration. By |
| the definition of host, this means that their host system is the same as |
| the target system of the overall configuration. |
| |
| The same process is used for both a native configuration and a cross |
| configuration. Even when using a native configuration, the target |
| libraries will be configured and built using the newly built compiler. |
| This is particularly important for the C++ libraries, since there is no |
| reason to assume that the C++ compiler used to build the host tools (if |
| there even is one) uses the same ABI as the g++ compiler which will be |
| used to build the target libraries. |
| |
| There is one difference between a native configuration and a cross |
| configuration. In a native configuration, the target libraries are |
| normally configured and built as siblings of the host tools. In a cross |
| configuration, the target libraries are normally built in a subdirectory |
| whose name is the argument to `--target'. This is mainly for |
| historical reasons. |
| |
| To summarize, running `configure' in the Cygnus tree configures all |
| the host libraries and tools, but does not configure any of the target |
| libraries. Running `make' then does the following steps: |
| |
| * Build the host libraries. |
| |
| * Build the host programs, including gcc. Note that we call gcc |
| both a host program (since it runs on the host) and a target |
| compiler (since it generates code for the target). |
| |
| * Using the newly built target compiler, configure the target |
| libraries. |
| |
| * Build the target libraries. |
| |
| The steps need not be done in precisely this order, since they are |
| actually controlled by `Makefile' targets. |
| |
| |
| File: configure.info, Node: Target Library Configure Scripts, Next: Make Targets in Cygnus Tree, Prev: Host and Target Libraries, Up: Cross Tools in the Cygnus Tree |
| |
| Target Library Configure Scripts |
| -------------------------------- |
| |
| There are a few things you must know in order to write a configure |
| script for a target library. This is just a quick sketch, and beginners |
| shouldn't worry if they don't follow everything here. |
| |
| The target libraries are configured and built using a newly built |
| target compiler. There may not be any startup files or libraries for |
| this target compiler. In fact, those files will probably be built as |
| part of some target library, which naturally means that they will not |
| exist when your target library is configured. |
| |
| This means that the configure script for a target library may not use |
| any test which requires doing a link. This unfortunately includes many |
| useful autoconf macros, such as `AC_CHECK_FUNCS'. autoconf macros |
| which do a compile but not a link, such as `AC_CHECK_HEADERS', may be |
| used. |
| |
| This is a severe restriction, but normally not a fatal one, as target |
| libraries can often assume the presence of other target libraries, and |
| thus know which functions will be available. |
| |
| As of this writing, the autoconf macro `AC_PROG_CC' does a link to |
| make sure that the compiler works. This may fail in a target library, |
| so target libraries must use a different set of macros to locate the |
| compiler. See the `configure.in' file in a directory like `libiberty' |
| or `libgloss' for an example. |
| |
| As noted in the previous section, target libraries are sometimes |
| built in directories which are siblings to the host tools, and are |
| sometimes built in a subdirectory. The `--with-target-subdir' configure |
| option will be passed when the library is configured. Its value will be |
| an empty string if the target library is a sibling. Its value will be |
| the name of the subdirectory if the target library is in a subdirectory. |
| |
| If the overall build is not a native build (i.e., the overall |
| configure used the `--target' option), then the library will be |
| configured with the `--with-cross-host' option. The value of this |
| option will be the host system of the overall build. Recall that the |
| host system of the library will be the target of the overall build. If |
| the overall build is a native build, the `--with-cross-host' option |
| will not be used. |
| |
| A library which can be built both standalone and as a target library |
| may want to install itself into different directories depending upon the |
| case. When built standalone, or when built native, the library should |
| be installed in `$(libdir)'. When built as a target library which is |
| not native, the library should be installed in `$(tooldir)/lib'. The |
| `--with-cross-host' option may be used to distinguish these cases. |
| |
| This same test of `--with-cross-host' may be used to see whether it |
| is OK to use link tests in the configure script. If the |
| `--with-cross-host' option is not used, then the library is being built |
| either standalone or native, and a link should work. |
| |
| |
| File: configure.info, Node: Make Targets in Cygnus Tree, Next: Target libiberty, Prev: Target Library Configure Scripts, Up: Cross Tools in the Cygnus Tree |
| |
| Make Targets in Cygnus Tree |
| --------------------------- |
| |
| The top level `Makefile' in the Cygnus tree defines targets for |
| every known subdirectory. |
| |
| For every subdirectory DIR which holds a host library or program, |
| the `Makefile' target `all-DIR' will build that library or program. |
| |
| There are dependencies among host tools. For example, building gcc |
| requires first building gas, because the gcc build process invokes the |
| target assembler. These dependencies are reflected in the top level |
| `Makefile'. |
| |
| For every subdirectory DIR which holds a target library, the |
| `Makefile' target `configure-target-DIR' will configure that library. |
| The `Makefile' target `all-target-DIR' will build that library. |
| |
| Every `configure-target-DIR' target depends upon `all-gcc', since |
| gcc, the target compiler, is required to configure the tool. Every |
| `all-target-DIR' target depends upon the corresponding |
| `configure-target-DIR' target. |
| |
| There are several other targets which may be of interest for each |
| directory: `install-DIR', `clean-DIR', and `check-DIR'. There are also |
| corresponding `target' versions of these for the target libraries , |
| such as `install-target-DIR'. |
| |
| |
| File: configure.info, Node: Target libiberty, Prev: Make Targets in Cygnus Tree, Up: Cross Tools in the Cygnus Tree |
| |
| Target libiberty |
| ---------------- |
| |
| The `libiberty' subdirectory is currently a special case, in that it |
| is the only directory which is built both using the host compiler and |
| using the target compiler. |
| |
| This is because the files in `libiberty' are used when building the |
| host tools, and they are also incorporated into the `libstdc++' target |
| library as support code. |
| |
| This duality does not pose any particular difficulties. It means |
| that there are targets for both `all-libiberty' and |
| `all-target-libiberty'. |
| |
| In a native configuration, when target libraries are not built in a |
| subdirectory, the same objects are normally used as both the host build |
| and the target build. This is normally OK, since libiberty contains |
| only C code, and in a native configuration the results of the host |
| compiler and the target compiler are normally interoperable. |
| |
| Irix 6 is again an exception here, since the SGI native compiler |
| defaults to using the `O32' ABI, and gcc defaults to using the `N32' |
| ABI. On Irix 6, the target libraries are built in a subdirectory even |
| for a native configuration, avoiding this problem. |
| |
| There are currently no other libraries built for both the host and |
| the target, but there is no conceptual problem with adding more. |
| |
| |
| File: configure.info, Node: Canadian Cross, Next: Cygnus Configure, Prev: Cross Compilation Tools, Up: Top |
| |
| Canadian Cross |
| ************** |
| |
| It is possible to use the GNU configure and build system to build a |
| program which will run on a system which is different from the system on |
| which the tools are built. In other words, it is possible to build |
| programs using a cross compiler. |
| |
| This is referred to as a "Canadian Cross". |
| |
| * Menu: |
| |
| * Canadian Cross Example:: Canadian Cross Example. |
| * Canadian Cross Concepts:: Canadian Cross Concepts. |
| * Build Cross Host Tools:: Build Cross Host Tools. |
| * Build and Host Options:: Build and Host Options. |
| * CCross not in Cygnus Tree:: Canadian Cross not in Cygnus Tree. |
| * CCross in Cygnus Tree:: Canadian Cross in Cygnus Tree. |
| * Supporting Canadian Cross:: Supporting Canadian Cross. |
| |
| |
| File: configure.info, Node: Canadian Cross Example, Next: Canadian Cross Concepts, Up: Canadian Cross |
| |
| Canadian Cross Example |
| ====================== |
| |
| Here is an example of a Canadian Cross. |
| |
| While running on a GNU/Linux, you can build a program which will run |
| on a Solaris system. You would use a GNU/Linux cross Solaris compiler |
| to build the program. |
| |
| Of course, you could not run the resulting program on your GNU/Linux |
| system. You would have to copy it over to a Solaris system before you |
| would run it. |
| |
| Of course, you could also simply build the programs on the Solaris |
| system in the first place. However, perhaps the Solaris system is not |
| available for some reason; perhaps you actually don't have one, but you |
| want to build the tools for somebody else to use. Or perhaps your |
| GNU/Linux system is much faster than your Solaris system. |
| |
| A Canadian Cross build is most frequently used when building |
| programs to run on a non-Unix system, such as DOS or Windows. It may |
| be simpler to configure and build on a Unix system than to support the |
| configuration machinery on a non-Unix system. |
| |
| |
| File: configure.info, Node: Canadian Cross Concepts, Next: Build Cross Host Tools, Prev: Canadian Cross Example, Up: Canadian Cross |
| |
| Canadian Cross Concepts |
| ======================= |
| |
| When building a Canadian Cross, there are at least two different |
| systems involved: the system on which the tools are being built, and |
| the system on which the tools will run. |
| |
| The system on which the tools are being built is called the "build" |
| system. |
| |
| The system on which the tools will run is called the host system. |
| |
| For example, if you are building a Solaris program on a GNU/Linux |
| system, as in the previous section, the build system would be GNU/Linux, |
| and the host system would be Solaris. |
| |
| It is, of course, possible to build a cross compiler using a Canadian |
| Cross (i.e., build a cross compiler using a cross compiler). In this |
| case, the system for which the resulting cross compiler generates code |
| is called the target system. (For a more complete discussion of host |
| and target systems, *note Host and Target::). |
| |
| An example of building a cross compiler using a Canadian Cross would |
| be building a Windows cross MIPS ELF compiler on a GNU/Linux system. In |
| this case the build system would be GNU/Linux, the host system would be |
| Windows, and the target system would be MIPS ELF. |
| |
| The name Canadian Cross comes from the case when the build, host, and |
| target systems are all different. At the time that these issues were |
| all being hashed out, Canada had three national political parties. |
| |
| |
| File: configure.info, Node: Build Cross Host Tools, Next: Build and Host Options, Prev: Canadian Cross Concepts, Up: Canadian Cross |
| |
| Build Cross Host Tools |
| ====================== |
| |
| In order to configure a program for a Canadian Cross build, you must |
| first build and install the set of cross tools you will use to build the |
| program. |
| |
| These tools will be build cross host tools. That is, they will run |
| on the build system, and will produce code that runs on the host system. |
| |
| It is easy to confuse the meaning of build and host here. Always |
| remember that the build system is where you are doing the build, and the |
| host system is where the resulting program will run. Therefore, you |
| need a build cross host compiler. |
| |
| In general, you must have a complete cross environment in order to do |
| the build. This normally means a cross compiler, cross assembler, and |
| so forth, as well as libraries and include files for the host system. |
| |
| |
| File: configure.info, Node: Build and Host Options, Next: CCross not in Cygnus Tree, Prev: Build Cross Host Tools, Up: Canadian Cross |
| |
| Build and Host Options |
| ====================== |
| |
| When you run `configure', you must use both the `--build' and |
| `--host' options. |
| |
| The `--build' option is used to specify the configuration name of |
| the build system. This can normally be the result of running the |
| `config.guess' shell script, and it is reasonable to use |
| `--build=`config.guess`'. |
| |
| The `--host' option is used to specify the configuration name of the |
| host system. |
| |
| As we explained earlier, `config.guess' is used to set the default |
| value for the `--host' option (*note Using the Host Type::). We can |
| now see that since `config.guess' returns the type of system on which |
| it is run, it really identifies the build system. Since the host |
| system is normally the same as the build system (i.e., people do not |
| normally build using a cross compiler), it is reasonable to use the |
| result of `config.guess' as the default for the host system when the |
| `--host' option is not used. |
| |
| It might seem that if the `--host' option were used without the |
| `--build' option that the configure script could run `config.guess' to |
| determine the build system, and presume a Canadian Cross if the result |
| of `config.guess' differed from the `--host' option. However, for |
| historical reasons, some configure scripts are routinely run using an |
| explicit `--host' option, rather than using the default from |
| `config.guess'. As noted earlier, it is difficult or impossible to |
| reliably compare configuration names (*note Using the Target Type::). |
| Therefore, by convention, if the `--host' option is used, but the |
| `--build' option is not used, then the build system defaults to the |
| host system. |
| |
| |
| File: configure.info, Node: CCross not in Cygnus Tree, Next: CCross in Cygnus Tree, Prev: Build and Host Options, Up: Canadian Cross |
| |
| Canadian Cross not in Cygnus Tree. |
| ================================== |
| |
| If you are not using the Cygnus tree, you must explicitly specify the |
| cross tools which you want to use to build the program. This is done by |
| setting environment variables before running the `configure' script. |
| |
| You must normally set at least the environment variables `CC', `AR', |
| and `RANLIB' to the cross tools which you want to use to build. |
| |
| For some programs, you must set additional cross tools as well, such |
| as `AS', `LD', or `NM'. |
| |
| You would set these environment variables to the build cross tools |
| which you are going to use. |
| |
| For example, if you are building a Solaris program on a GNU/Linux |
| system, and your GNU/Linux cross Solaris compiler were named |
| `solaris-gcc', then you would set the environment variable `CC' to |
| `solaris-gcc'. |
| |
| |
| File: configure.info, Node: CCross in Cygnus Tree, Next: Supporting Canadian Cross, Prev: CCross not in Cygnus Tree, Up: Canadian Cross |
| |
| Canadian Cross in Cygnus Tree |
| ============================= |
| |
| This section describes configuring and building a Canadian Cross when |
| using the Cygnus tree. |
| |
| * Menu: |
| |
| * Standard Cygnus CCross:: Building a Normal Program. |
| * Cross Cygnus CCross:: Building a Cross Program. |
| |
| |
| File: configure.info, Node: Standard Cygnus CCross, Next: Cross Cygnus CCross, Up: CCross in Cygnus Tree |
| |
| Building a Normal Program |
| ------------------------- |
| |
| When configuring a Canadian Cross in the Cygnus tree, all the |
| appropriate environment variables are automatically set to `HOST-TOOL', |
| where HOST is the value used for the `--host' option, and TOOL is the |
| name of the tool (e.g., `gcc', `as', etc.). These tools must be on |
| your `PATH'. |
| |
| Adding a prefix of HOST will give the usual name for the build cross |
| host tools. To see this, consider that when these cross tools were |
| built, they were configured to run on the build system and to produce |
| code for the host system. That is, they were configured with a |
| `--target' option that is the same as the system which we are now |
| calling the host. Recall that the default name for installed cross |
| tools uses the target system as a prefix (*note Using the Target |
| Type::). Since that is the system which we are now calling the host, |
| HOST is the right prefix to use. |
| |
| For example, if you configure with `--build=i386-linux-gnu' and |
| `--host=solaris', then the Cygnus tree will automatically default to |
| using the compiler `solaris-gcc'. You must have previously built and |
| installed this compiler, probably by doing a build with no `--host' |
| option and with a `--target' option of `solaris'. |
| |
| |
| File: configure.info, Node: Cross Cygnus CCross, Prev: Standard Cygnus CCross, Up: CCross in Cygnus Tree |
| |
| Building a Cross Program |
| ------------------------ |
| |
| There are additional considerations if you want to build a cross |
| compiler, rather than a native compiler, in the Cygnus tree using a |
| Canadian Cross. |
| |
| When you build a cross compiler using the Cygnus tree, then the |
| target libraries will normally be built with the newly built target |
| compiler (*note Host and Target Libraries::). However, this will not |
| work when building with a Canadian Cross. This is because the newly |
| built target compiler will be a program which runs on the host system, |
| and therefore will not be able to run on the build system. |
| |
| Therefore, when building a cross compiler with the Cygnus tree, you |
| must first install a set of build cross target tools. These tools will |
| be used when building the target libraries. |
| |
| Note that this is not a requirement of a Canadian Cross in general. |
| For example, it would be possible to build just the host cross target |
| tools on the build system, to copy the tools to the host system, and to |
| build the target libraries on the host system. The requirement for |
| build cross target tools is imposed by the Cygnus tree, which expects |
| to be able to build both host programs and target libraries in a single |
| `configure'/`make' step. Because it builds these in a single step, it |
| expects to be able to build the target libraries on the build system, |
| which means that it must use a build cross target toolchain. |
| |
| For example, suppose you want to build a Windows cross MIPS ELF |
| compiler on a GNU/Linux system. You must have previously installed |
| both a GNU/Linux cross Windows compiler and a GNU/Linux cross MIPS ELF |
| compiler. |
| |
| In order to build the Windows (configuration name `i386-cygwin32') |
| cross MIPS ELF (configure name `mips-elf') compiler, you might execute |
| the following commands (long command lines are broken across lines with |
| a trailing backslash as a continuation character). |
| |
| mkdir linux-x-cygwin32 |
| cd linux-x-cygwin32 |
| SRCDIR/configure --target i386-cygwin32 --prefix=INSTALLDIR \ |
| --exec-prefix=INSTALLDIR/H-i386-linux |
| make |
| make install |
| cd .. |
| mkdir linux-x-mips-elf |
| cd linux-x-mips-elf |
| SRCDIR/configure --target mips-elf --prefix=INSTALLDIR \ |
| --exec-prefix=INSTALLDIR/H-i386-linux |
| make |
| make install |
| cd .. |
| mkdir cygwin32-x-mips-elf |
| cd cygwin32-x-mips-elf |
| SRCDIR/configure --build=i386-linux-gnu --host=i386-cygwin32 \ |
| --target=mips-elf --prefix=WININSTALLDIR \ |
| --exec-prefix=WININSTALLDIR/H-i386-cygwin32 |
| make |
| make install |
| |
| You would then copy the contents of WININSTALLDIR over to the |
| Windows machine, and run the resulting programs. |
| |
| |
| File: configure.info, Node: Supporting Canadian Cross, Prev: CCross in Cygnus Tree, Up: Canadian Cross |
| |
| Supporting Canadian Cross |
| ========================= |
| |
| If you want to make it possible to build a program you are developing |
| using a Canadian Cross, you must take some care when writing your |
| configure and make rules. Simple cases will normally work correctly. |
| However, it is not hard to write configure and make tests which will |
| fail in a Canadian Cross. |
| |
| * Menu: |
| |
| * CCross in Configure:: Supporting Canadian Cross in Configure Scripts. |
| * CCross in Make:: Supporting Canadian Cross in Makefiles. |
| |
| |
| File: configure.info, Node: CCross in Configure, Next: CCross in Make, Up: Supporting Canadian Cross |
| |
| Supporting Canadian Cross in Configure Scripts |
| ---------------------------------------------- |
| |
| In a `configure.in' file, after calling `AC_PROG_CC', you can find |
| out whether this is a Canadian Cross configure by examining the shell |
| variable `cross_compiling'. In a Canadian Cross, which means that the |
| compiler is a cross compiler, `cross_compiling' will be `yes'. In a |
| normal configuration, `cross_compiling' will be `no'. |
| |
| You ordinarily do not need to know the type of the build system in a |
| configure script. However, if you do need that information, you can get |
| it by using the macro `AC_CANONICAL_SYSTEM', the same macro that is |
| used to determine the target system. This macro will set the variables |
| `build', `build_alias', `build_cpu', `build_vendor', and `build_os', |
| which correspond to the similar `target' and `host' variables, except |
| that they describe the build system. |
| |
| When writing tests in `configure.in', you must remember that you |
| want to test the host environment, not the build environment. |
| |
| Macros like `AC_CHECK_FUNCS' which use the compiler will test the |
| host environment. That is because the tests will be done by running the |
| compiler, which is actually a build cross host compiler. If the |
| compiler can find the function, that means that the function is present |
| in the host environment. |
| |
| Tests like `test -f /dev/ptyp0', on the other hand, will test the |
| build environment. Remember that the configure script is running on the |
| build system, not the host system. If your configure scripts examines |
| files, those files will be on the build system. Whatever you determine |
| based on those files may or may not be the case on the host system. |
| |
| Most autoconf macros will work correctly for a Canadian Cross. The |
| main exception is `AC_TRY_RUN'. This macro tries to compile and run a |
| test program. This will fail in a Canadian Cross, because the program |
| will be compiled for the host system, which means that it will not run |
| on the build system. |
| |
| The `AC_TRY_RUN' macro provides an optional argument to tell the |
| configure script what to do in a Canadian Cross. If that argument is |
| not present, you will get a warning when you run `autoconf': |
| warning: AC_TRY_RUN called without default to allow cross compiling |
| |
| This tells you that the resulting `configure' script will not work with |
| a Canadian Cross. |
| |
| In some cases while it may better to perform a test at configure |
| time, it is also possible to perform the test at run time. In such a |
| case you can use the cross compiling argument to `AC_TRY_RUN' to tell |
| your program that the test could not be performed at configure time. |
| |
| There are a few other autoconf macros which will not work correctly |
| with a Canadian Cross: a partial list is `AC_FUNC_GETPGRP', |
| `AC_FUNC_SETPGRP', `AC_FUNC_SETVBUF_REVERSED', and |
| `AC_SYS_RESTARTABLE_SYSCALLS'. The `AC_CHECK_SIZEOF' macro is |
| generally not very useful with a Canadian Cross; it permits an optional |
| argument indicating the default size, but there is no way to know what |
| the correct default should be. |
| |
| |
| File: configure.info, Node: CCross in Make, Prev: CCross in Configure, Up: Supporting Canadian Cross |
| |
| Supporting Canadian Cross in Makefiles. |
| --------------------------------------- |
| |
| The main Canadian Cross issue in a `Makefile' arises when you want |
| to use a subsidiary program to generate code or data which you will then |
| include in your real program. |
| |
| If you compile this subsidiary program using `$(CC)' in the usual |
| way, you will not be able to run it. This is because `$(CC)' will |
| build a program for the host system, but the program is being built on |
| the build system. |
| |
| You must instead use a compiler for the build system, rather than the |
| host system. In the Cygnus tree, this make variable `$(CC_FOR_BUILD)' |
| will hold a compiler for the build system. |
| |
| Note that you should not include `config.h' in a file you are |
| compiling with `$(CC_FOR_BUILD)'. The `configure' script will build |
| `config.h' with information for the host system. However, you are |
| compiling the file using a compiler for the build system (a native |
| compiler). Subsidiary programs are normally simple filters which do no |
| user interaction, and it is normally possible to write them in a highly |
| portable fashion so that the absence of `config.h' is not crucial. |
| |
| The gcc `Makefile.in' shows a complex situation in which certain |
| files, such as `rtl.c', must be compiled into both subsidiary programs |
| run on the build system and into the final program. This approach may |
| be of interest for advanced build system hackers. Note that the build |
| system compiler is rather confusingly called `HOST_CC'. |
| |
| |
| File: configure.info, Node: Cygnus Configure, Next: Multilibs, Prev: Canadian Cross, Up: Top |
| |
| Cygnus Configure |
| **************** |
| |
| The Cygnus configure script predates autoconf. All of its |
| interesting features have been incorporated into autoconf. No new |
| programs should be written to use the Cygnus configure script. |
| |
| However, the Cygnus configure script is still used in a few places: |
| at the top of the Cygnus tree and in a few target libraries in the |
| Cygnus tree. Until those uses have been replaced with autoconf, some |
| brief notes are appropriate here. This is not complete documentation, |
| but it should be possible to use this as a guide while examining the |
| scripts themselves. |
| |
| * Menu: |
| |
| * Cygnus Configure Basics:: Cygnus Configure Basics. |
| * Cygnus Configure in C++ Libraries:: Cygnus Configure in C++ Libraries. |
| |
| |
| File: configure.info, Node: Cygnus Configure Basics, Next: Cygnus Configure in C++ Libraries, Up: Cygnus Configure |
| |
| Cygnus Configure Basics |
| ======================= |
| |
| Cygnus configure does not use any generated files; there is no |
| program corresponding to `autoconf'. Instead, there is a single shell |
| script named `configure' which may be found at the top of the Cygnus |
| tree. This shell script was written by hand; it was not generated by |
| autoconf, and it is incorrect, and indeed harmful, to run `autoconf' in |
| the top level of a Cygnus tree. |
| |
| Cygnus configure works in a particular directory by examining the |
| file `configure.in' in that directory. That file is broken into four |
| separate shell scripts. |
| |
| The first is the contents of `configure.in' up to a line that starts |
| with `# per-host:'. This is the common part. |
| |
| The second is the rest of `configure.in' up to a line that starts |
| with `# per-target:'. This is the per host part. |
| |
| The third is the rest of `configure.in' up to a line that starts |
| with `# post-target:'. This is the per target part. |
| |
| The fourth is the remainder of `configure.in'. This is the post |
| target part. |
| |
| If any of these comment lines are missing, the corresponding shell |
| script is empty. |
| |
| Cygnus configure will first execute the common part. This must set |
| the shell variable `srctrigger' to the name of a source file, to |
| confirm that Cygnus configure is looking at the right directory. This |
| may set the shell variables `package_makefile_frag' and |
| `package_makefile_rules_frag'. |
| |
| Cygnus configure will next set the `build' and `host' shell |
| variables, and execute the per host part. This may set the shell |
| variable `host_makefile_frag'. |
| |
| Cygnus configure will next set the `target' variable, and execute |
| the per target part. This may set the shell variable |
| `target_makefile_frag'. |
| |
| Any of these scripts may set the `subdirs' shell variable. This |
| variable is a list of subdirectories where a `Makefile.in' file may be |
| found. Cygnus configure will automatically look for a `Makefile.in' |
| file in the current directory. The `subdirs' shell variable is not |
| normally used, and I believe that the only directory which uses it at |
| present is `newlib'. |
| |
| For each `Makefile.in', Cygnus configure will automatically create a |
| `Makefile' by adding definitions for `make' variables such as `host' |
| and `target', and automatically editing the values of `make' variables |
| such as `prefix' if they are present. |
| |
| Also, if any of the `makefile_frag' shell variables are set, Cygnus |
| configure will interpret them as file names relative to either the |
| working directory or the source directory, and will read the contents of |
| the file into the generated `Makefile'. The file contents will be read |
| in after the first line in `Makefile.in' which starts with `####'. |
| |
| These `Makefile' fragments are used to customize behaviour for a |
| particular host or target. They serve to select particular files to |
| compile, and to define particular preprocessor macros by providing |
| values for `make' variables which are then used during compilation. |
| Cygnus configure, unlike autoconf, normally does not do feature tests, |
| and normally requires support to be added manually for each new host. |
| |
| The `Makefile' fragment support is similar to the autoconf |
| `AC_SUBST_FILE' macro. |
| |
| After creating each `Makefile', the post target script will be run |
| (i.e., it may be run several times). This script may further customize |
| the `Makefile'. When it is run, the shell variable `Makefile' will |
| hold the name of the `Makefile', including the appropriate directory |
| component. |
| |
| Like an autoconf generated `configure' script, Cygnus configure will |
| create a file named `config.status' which, when run, will automatically |
| recreate the configuration. The `config.status' file will simply |
| execute the Cygnus configure script again with the appropriate |
| arguments. |
| |
| Any of the parts of `configure.in' may set the shell variables |
| `files' and `links'. Cygnus configure will set up symlinks from the |
| names in `links' to the files named in `files'. This is similar to the |
| autoconf `AC_LINK_FILES' macro. |
| |
| Finally, any of the parts of `configure.in' may set the shell |
| variable `configdirs' to a set of subdirectories. If it is set, Cygnus |
| configure will recursively run the configure process in each |
| subdirectory. If the subdirectory uses Cygnus configure, it will |
| contain a `configure.in' file but no `configure' file, in which case |
| Cygnus configure will invoke itself recursively. If the subdirectory |
| has a `configure' file, Cygnus configure assumes that it is an autoconf |
| generated `configure' script, and simply invokes it directly. |
| |
| |
| File: configure.info, Node: Cygnus Configure in C++ Libraries, Prev: Cygnus Configure Basics, Up: Cygnus Configure |
| |
| Cygnus Configure in C++ Libraries |
| ================================= |
| |
| The C++ library configure system, written by Per Bothner, deserves |
| special mention. It uses Cygnus configure, but it does feature testing |
| like that done by autoconf generated `configure' scripts. This |
| approach is used in the libraries `libio', `libstdc++', and `libg++'. |
| |
| Most of the `Makefile' information is written out by the shell |
| script `libio/config.shared'. Each `configure.in' file sets certain |
| shell variables, and then invokes `config.shared' to create two package |
| `Makefile' fragments. These fragments are then incorporated into the |
| resulting `Makefile' by the Cygnus configure script. |
| |
| The file `_G_config.h' is created in the `libio' object directory by |
| running the shell script `libio/gen-params'. This shell script uses |
| feature tests to define macros and typedefs in `_G_config.h'. |
| |
| |
| File: configure.info, Node: Multilibs, Next: FAQ, Prev: Cygnus Configure, Up: Top |
| |
| Multilibs |
| ********* |
| |
| For some targets gcc may have different processor requirements |
| depending upon command line options. An obvious example is the |
| `-msoft-float' option supported on several processors. This option |
| means that the floating point registers are not available, which means |
| that floating point operations must be done by calling an emulation |
| subroutine rather than by using machine instructions. |
| |
| For such options, gcc is often configured to compile target libraries |
| twice: once with `-msoft-float' and once without. When gcc compiles |
| target libraries more than once, the resulting libraries are called |
| "multilibs". |
| |
| Multilibs are not really part of the GNU configure and build system, |
| but we discuss them here since they require support in the `configure' |
| scripts and `Makefile's used for target libraries. |
| |
| * Menu: |
| |
| * Multilibs in gcc:: Multilibs in gcc. |
| * Multilibs in Target Libraries:: Multilibs in Target Libraries. |
| |
| |
| File: configure.info, Node: Multilibs in gcc, Next: Multilibs in Target Libraries, Up: Multilibs |
| |
| Multilibs in gcc |
| ================ |
| |
| In gcc, multilibs are defined by setting the variable |
| `MULTILIB_OPTIONS' in the target `Makefile' fragment. Several other |
| `MULTILIB' variables may also be defined there. *Note The Target |
| Makefile Fragment: (gcc)Target Fragment. |
| |
| If you have built gcc, you can see what multilibs it uses by running |
| it with the `-print-multi-lib' option. The output `.;' means that no |
| multilibs are used. In general, the output is a sequence of lines, one |
| per multilib. The first part of each line, up to the `;', is the name |
| of the multilib directory. The second part is a list of compiler |
| options separated by `@' characters. |
| |
| Multilibs are built in a tree of directories. The top of the tree, |
| represented by `.' in the list of multilib directories, is the default |
| library to use when no special compiler options are used. The |
| subdirectories of the tree hold versions of the library to use when |
| particular compiler options are used. |
| |