Initial revision
[external/binutils.git] / README.configure
1
2
3                             Configuration
4
5          Last Mod Fri Apr 12 13:32:56 PDT 1991, by rich@sendai
6
7
8 "Theory":
9
10 In this document, the word "host" refers to the environment in which
11 this source will be compiled.  "host" and "host name" have nothing to
12 do with the proper name of your host, like "ucbvax", "prep.ai.mit.edu"
13 or "att.com".  Instead they refer to things like "sun4" and "dec3100".
14
15 Forget for a moment that this particular directory of source is the
16 source for a development environment.  Instead, pretend that it is the
17 source for a simpler, more mundane, application, say, a desk
18 calculator.
19
20 Source that can be compiled in more than one environment, generally
21 needs to be set up for each environment explicitly. 
22
23 The word "target" refers to the environment produced by compiling this
24 source and installing the resulting binaries.
25
26 For example, if configured for host sun4 and target sun4, this implies
27 that we will compile on a sun4 to create a sun4 compilation
28 environment.  If configured for host sun3 and target a29k, this
29 implies that we will compile on a sun3 to create an a29k compilation
30 environment.
31
32 Host sun3 only implies that the source will be compiled on a sun3.  In
33 fact, it need not be actually compiled on a sun3.  If the appropriate
34 native development tools, header files, libraries, and operating
35 system support were available on a foobox, then source configured for
36 a sun3 could be compiled on a foobox, resulting in a development
37 environment for, using the previous example host+target pair, "a29k"
38 on the foobox.  Similarly, if the appropriate cross development tools,
39 header files, and libraries were available on a dec3100, then source
40 configured for host sun3 could be cross compiled to create an a29k 
41 development environment intended to be run on a sun3.
42
43
44 Usage:
45
46 Gdb's config has features not yet present in the uniform configuration
47 scheme described here.  For this reason, configuration of gdb must
48 currently be done separately from that of the rest of this package.
49 This will be corrected soon.  For more information on the
50 configuration of gdb, please refer to the documents in gdb.{your
51 target} if it exists, otherwise gdb.
52
53 By "configures", I mean that links, Makefile, .gdbinit, and
54 config.status are built.  Configuration is always done from the source
55 directory.
56
57 * "./configure name" configures this directory, perhaps
58   recursively, for a single host+target pair where the host and target
59   are both "name".  If a previous configuration existed, it will be
60   overwritten.
61
62 * "./configure +host=hostname targetname" configures this
63   directory, perhaps recursively, for a single host+target pair where
64   the host is hostname and target is targetname.  If a previous
65   configuration existed, it will be overwritten.
66
67 * "./configure +forcesubdirs +host=hostname targetname" creates
68   a subdirectories Host-hostname and
69   Host-hostname/Target-targetname and configures
70   Host-hostname/Target-targetname.  For now, makes should be
71   done from Host-hostname/Target-targetname.  "./configure +f
72   name" works as expected.  That is, it creates Host-name and
73   Host-name/Target-name and configures the latter.
74
75
76 Hacking configurations:
77
78 The configure scripts essentially do three things, create
79 subdirectories if appropriate, build a Makefile, and create links to
80 files, all based on and tailored to, a specific host+target pair.  The
81 scripts also create a .gdbinit if appropriate but this is not
82 tailored.
83
84 The Makefile is created by prepending some variable definitions to a
85 Makefile template called Makefile.in and then inserting host and
86 target specific Makefile fragments.  The variables are set based on
87 the chosen host+target pair and build style, that is, if you use
88 subdirectories or not.  The host and target specific Makefile
89 may or may not exist.  If fragments 
90
91 * Makefiles can be editted directly, but those changes will eventually
92   be lost.  Changes intended to be permanent for a specific host
93   should be made to the host specific Makefile fragment.  This should
94   be in ./config/hmake-host if it exists.  Changes intended to be
95   permanent for a specific target should be made to the target
96   specific Makefile fragment.  This should be in ./config/tmake-target
97   if it exists.  Changes intended to be permanent for the directory
98   should be made in Makefile.in.  To propogate changes to any of
99   these, either use "make Makefile" or re-configure from the source
100   directory.
101
102 * configure can be editted directly, but those changes will eventually
103   be lost.  Changes intended to be permanent for a specific directory
104   should be made to configure.in.  Changes intended to be permanent
105   for all configure scripts should be made to configure.template.
106   Propogating changes to configure.in requires the presence of
107   configure.template which normally resides in the uppermost directory
108   you received.  To propogate changes to either configure.template or
109   a configure.in, use "configure +template=absolutepathtothetemplate".
110   This will configure the configure scripts themselves, recursively if
111   appropriate.
112
113 * "configure -srcdir=foo" is not supported yet.  At the moment, things
114   will probably be configured correctly only for leaf directories, and
115   even they will not have paths to libraries set properly.