Commit | Line | Data |
---|---|---|
1b577b00 | 1 | README for BINUTILS |
252b5132 | 2 | |
1b577b00 NC |
3 | These are the GNU binutils. These are utilities of use when dealing |
4 | with binary files, either object files or executables. These tools | |
5 | consist of the linker (ld), the assembler (gas), and the profiler | |
6 | (gprof) each of which have their own sub-directory named after them. | |
7 | There is also a collection of other binary tools, including the | |
8 | disassembler (objdump) in this directory. These tools make use of a | |
9 | pair of libraries (bfd and opcodes) and a common set of header files | |
10 | (include). | |
252b5132 | 11 | |
1b577b00 NC |
12 | There are README and NEWS files in most of the program sub-directories |
13 | which give more information about those specific programs. | |
252b5132 | 14 | |
252b5132 | 15 | |
2c80b753 AM |
16 | Copyright Notices |
17 | ================= | |
18 | ||
19 | Copyright years on binutils source files may be listed using range | |
20 | notation, e.g., 1991-2012, indicating that every year in the range, | |
21 | inclusive, is a copyrightable year that could otherwise be listed | |
22 | individually. | |
23 | ||
24 | ||
252b5132 RH |
25 | Unpacking and Installation -- quick overview |
26 | ============================================ | |
27 | ||
1b577b00 NC |
28 | When you unpack the binutils archive file, you will get a directory |
29 | called something like `binutils-XXX', where XXX is the number of the | |
a99996bb | 30 | release. (Probably 2.13 or higher). This directory contains |
1b577b00 NC |
31 | various files and sub-directories. Most of the files in the top |
32 | directory are for information and for configuration. The actual | |
33 | source code is in sub-directories. | |
252b5132 RH |
34 | |
35 | To build binutils, you can just do: | |
36 | ||
1b577b00 | 37 | cd binutils-XXX |
252b5132 RH |
38 | ./configure [options] |
39 | make | |
40 | make install # copies the programs files into /usr/local/bin | |
41 | # by default. | |
42 | ||
43 | This will configure and build all the libraries as well as the | |
44 | assembler, the binutils, and the linker. | |
45 | ||
46 | If you have GNU make, we recommend building in a different directory: | |
47 | ||
48 | mkdir objdir | |
49 | cd objdir | |
1b577b00 | 50 | ../binutils-XXX/configure [options] |
252b5132 RH |
51 | make |
52 | make install | |
53 | ||
54 | This relies on the VPATH feature of GNU make. | |
55 | ||
56 | By default, the binutils will be configured to support the system on | |
57 | which they are built. When doing cross development, use the --target | |
1b577b00 NC |
58 | configure option to specify a different target, eg: |
59 | ||
60 | ./configure --target=foo-elf | |
252b5132 RH |
61 | |
62 | The --enable-targets option adds support for more binary file formats | |
63 | besides the default. List them as the argument to --enable-targets, | |
64 | separated by commas. For example: | |
65 | ||
66 | ./configure --enable-targets=sun3,rs6000-aix,decstation | |
67 | ||
1b577b00 | 68 | The name 'all' compiles in support for all valid BFD targets: |
252b5132 RH |
69 | |
70 | ./configure --enable-targets=all | |
71 | ||
1b577b00 NC |
72 | On 32-bit hosts though, this support will be restricted to 32-bit |
73 | target unless the --enable-64-bit-bfd option is also used: | |
74 | ||
75 | ./configure --enable-64-bit-bfd --enable-targets=all | |
1aa604e1 | 76 | |
252b5132 RH |
77 | You can also specify the --enable-shared option when you run |
78 | configure. This will build the BFD and opcodes libraries as shared | |
79 | libraries. You can use arguments with the --enable-shared option to | |
80 | indicate that only certain libraries should be built shared; for | |
81 | example, --enable-shared=bfd. The only potential shared libraries in | |
82 | a binutils release are bfd and opcodes. | |
83 | ||
84 | The binutils will be linked against the shared libraries. The build | |
1b577b00 | 85 | step will attempt to place the correct library in the run-time search |
252b5132 RH |
86 | path for the binaries. However, in some cases, after you install the |
87 | binaries, you may have to set an environment variable, normally | |
88 | LD_LIBRARY_PATH, so that the system can find the installed libbfd | |
89 | shared library. | |
90 | ||
1aa604e1 NC |
91 | On hosts that support shared system libraries the binutils will be |
92 | linked against them. If you have static versions of the system | |
93 | libraries installed as well and you wish to create static binaries | |
94 | instead then use the LDFLAGS environment variable, like this: | |
95 | ||
96 | ../binutils-XXX/configure LDFLAGS="--static" [more options] | |
97 | ||
98 | Note: the two dashes are important. The binutils make use of the | |
99 | libtool script which has a special interpretation of "-static" when it | |
100 | is in the LDFLAGS environment variable. | |
101 | ||
252b5132 RH |
102 | To build under openVMS/AXP, see the file makefile.vms in the top level |
103 | directory. | |
104 | ||
1b577b00 | 105 | |
a99996bb NC |
106 | Native Language Support |
107 | ======================= | |
108 | ||
109 | By default Native Language Support will be enabled for binutils. On | |
110 | some systems however this support is not present and can lead to error | |
111 | messages such as "undefined reference to `libintl_gettext'" when | |
112 | building there tools. If that happens the NLS support can be disabled | |
113 | by adding the --disable-nls switch to the configure line like this: | |
114 | ||
115 | ../binutils-XXX/configure --disable-nls | |
116 | ||
117 | ||
252b5132 RH |
118 | If you don't have ar |
119 | ==================== | |
120 | ||
1b577b00 | 121 | If your system does not already have an 'ar' program, the normal |
252b5132 RH |
122 | binutils build process will not work. In this case, run configure as |
123 | usual. Before running make, run this script: | |
124 | ||
125 | #!/bin/sh | |
126 | MAKE_PROG="${MAKE-make}" | |
127 | MAKE="${MAKE_PROG} AR=true LINK=true" | |
128 | export MAKE | |
129 | ${MAKE} $* all-libiberty | |
130 | ${MAKE} $* all-intl | |
131 | ${MAKE} $* all-bfd | |
132 | cd binutils | |
133 | MAKE="${MAKE_PROG}" | |
134 | export MAKE | |
08213ebb | 135 | ${MAKE} $* ar_DEPENDENCIES= ar_LDADD='../bfd/*.o ../libiberty/*.o `if test -f ../intl/gettext.o; then echo '../intl/*.o'; fi`' ar |
252b5132 RH |
136 | |
137 | This script will build an ar program in binutils/ar. Move binutils/ar | |
138 | into a directory on your PATH. After doing this, you can run make as | |
139 | usual to build the complete binutils distribution. You do not need | |
140 | the ranlib program in order to build the distribution. | |
141 | ||
142 | Porting | |
143 | ======= | |
144 | ||
a99996bb | 145 | Binutils-2.13 supports many different architectures, but there |
252b5132 | 146 | are many more not supported, including some that were supported |
1b577b00 NC |
147 | by earlier versions. We are hoping for volunteers to improve this |
148 | situation. | |
252b5132 RH |
149 | |
150 | The major effort in porting binutils to a new host and/or target | |
151 | architecture involves the BFD library. There is some documentation | |
152 | in ../bfd/doc. The file ../gdb/doc/gdbint.texinfo (distributed | |
effb0601 | 153 | with gdb-5.x) may also be of help. |
252b5132 RH |
154 | |
155 | Reporting bugs | |
156 | ============== | |
157 | ||
1b577b00 NC |
158 | Send bug reports and patches to: |
159 | ||
1f554c69 | 160 | bug-binutils@gnu.org. |
1b577b00 | 161 | |
36fd3cc3 AM |
162 | Please include the following in bug reports: |
163 | ||
164 | - A description of exactly what went wrong, and exactly what should have | |
165 | happened instead. | |
166 | ||
167 | - The configuration name(s) given to the "configure" script. The | |
168 | "config.status" file should have this information. This is assuming | |
169 | you built binutils yourself. If you didn't build binutils youself, | |
170 | then we need information regarding your machine and operating system, | |
171 | and it may be more appropriate to report bugs to wherever you obtained | |
172 | binutils. | |
173 | ||
174 | - The options given to the tool (gas, objcopy, ld etc.) at run time. | |
175 | ||
176 | - The actual input file that caused the problem. | |
177 | ||
1b577b00 NC |
178 | Always mention the version number you are running; this is printed by |
179 | running any of the binutils with the --version option. We appreciate | |
36fd3cc3 AM |
180 | reports about bugs, but we do not promise to fix them, particularly so |
181 | when the bug report is against an old version. If you are able, please | |
20cef68c | 182 | consider building the latest tools from git to check that your bug has |
36fd3cc3 AM |
183 | not already been fixed. |
184 | ||
185 | When reporting problems about gas and ld, it's useful to provide a | |
186 | testcase that triggers the problem. In the case of a gas problem, we | |
187 | want input files to gas and command line switches used. The inputs to | |
188 | gas are _NOT_ .c or .i files, but rather .s files. If your original | |
189 | source was a C program, you can generate the .s file and see the command | |
190 | line options by passing -v -save-temps to gcc in addition to all the | |
191 | usual options you use. The reason we don't want C files is that we | |
192 | might not have a C compiler around for the target you use. While it | |
193 | might be possible to build a compiler, that takes considerable time and | |
194 | disk space, and we might not end up with exactly the same compiler you | |
195 | use. | |
196 | ||
197 | In the case of a ld problem, the input files are .o, .a and .so files, | |
198 | and possibly a linker script specified with -T. Again, when using gcc | |
199 | to link, you can see these files by adding options to the gcc command | |
200 | line. Use -v -save-temps -Wl,-t, except that on targets that use gcc's | |
201 | collect2, you would add -v -save-temps -Wl,-t,-debug. The -t option | |
202 | tells ld to print all files and libraries used, so that, for example, | |
203 | you can associate -lc on the ld command line with the actual libc used. | |
204 | Note that your simple two line C program to trigger a problem typically | |
205 | expands into several megabytes of objects by the time you include | |
206 | libraries. | |
207 | ||
208 | It is antisocial to post megabyte sized attachments to mailing lists, so | |
209 | please put large testcases somewhere on an ftp or web site so that only | |
210 | interested developers need to download them, or offer to email them on | |
211 | request. Better still, try to reduce the testcase, for example, try to | |
212 | develop a ld testcase that doesn't use system libraries. However, | |
213 | please be sure it is a complete testcase and that it really does | |
214 | demonstrate the problem. Also, don't bother paring it down if that will | |
215 | cause large delays in filing the bug report. | |
216 | ||
217 | If you expect to be contributing a large number of test cases, it would | |
218 | be helpful if you would look at the test suite included in the release | |
219 | (based on the Deja Gnu testing framework, available from the usual ftp | |
220 | sites) and write test cases to fit into that framework. This is | |
221 | certainly not required. | |
252b5132 RH |
222 | |
223 | VMS | |
224 | === | |
225 | ||
226 | This section was written by Klaus K"ampf <kkaempf@rmi.de>. It | |
227 | describes how to build and install the binutils on openVMS (Alpha and | |
228 | Vax). (The BFD library only supports reading Vax object files.) | |
229 | ||
230 | Compiling the release: | |
231 | ||
232 | To compile the gnu binary utilities and the gnu assembler, you'll | |
233 | need DEC C or GNU C for openVMS/Alpha. You'll need *both* compilers | |
234 | on openVMS/Vax. | |
235 | ||
236 | Compiling with either DEC C or GNU C works on openVMS/Alpha only. Some | |
237 | of the opcodes and binutils files trap a bug in the DEC C optimizer, | |
238 | so these files must be compiled with /noopt. | |
239 | ||
240 | Compiling on openVMS/Vax is a bit complicated, as the bfd library traps | |
241 | a bug in GNU C and the gnu assembler a bug in (my version of) DEC C. | |
242 | ||
243 | I never tried compiling with VAX C. | |
244 | ||
245 | ||
246 | You further need GNU Make Version 3.76 or later. This is available | |
247 | at ftp.progis.de or any GNU archive site. The makefiles assume that | |
248 | gmake starts gnu make as a foreign command. | |
249 | ||
250 | If you're compiling with DEC C or VAX C, you must run | |
251 | ||
252 | $ @setup | |
253 | ||
254 | before starting gnu-make. This isn't needed with GNU C. | |
255 | ||
256 | On the Alpha you can choose the compiler by editing the toplevel | |
257 | makefile.vms. Either select CC=cc (for DEC C) or CC=gcc (for GNU C) | |
258 | ||
259 | ||
260 | Installing the release | |
261 | ||
262 | Provided that your directory setup conforms to the GNU on openVMS | |
1b577b00 | 263 | standard, you already have a concealed device named 'GNU_ROOT'. |
252b5132 RH |
264 | In this case, a simple |
265 | ||
266 | $ gmake install | |
267 | ||
268 | suffices to copy all programs and libraries to the proper directories. | |
269 | ||
270 | Define the programs as foreign commands by adding these lines to your | |
271 | login.com: | |
272 | ||
273 | $ gas :== $GNU_ROOT:[bin]as.exe | |
274 | $ size :== $GNU_ROOT:[bin]size.exe | |
275 | $ nm :== $GNU_ROOT:[bin]nm.exe | |
276 | $ objdump :== $GNU_ROOT:[bin]objdump.exe | |
277 | $ strings :== $GNU_ROOT:[bin]strings.exe | |
278 | ||
279 | If you have a different directory setup, copy the binary utilities | |
280 | ([.binutils]size.exe, [.binutils]nm.exe, [.binutils]objdump.exe, | |
281 | and [.binutils]strings.exe) and the gnu assembler and preprocessor | |
282 | ([.gas]as.exe and [.gas]gasp.exe]) to a directory of your choice | |
283 | and define all programs as foreign commands. | |
284 | ||
285 | ||
1b577b00 | 286 | If you're satisfied with the compilation, you may want to remove |
252b5132 RH |
287 | unneeded objects and libraries: |
288 | ||
289 | $ gmake clean | |
290 | ||
291 | ||
292 | If you have any problems or questions about the binutils on VMS, feel | |
293 | free to mail me at kkaempf@rmi.de. | |
5bf135a7 | 294 | \f |
b90efa5b | 295 | Copyright (C) 2012-2015 Free Software Foundation, Inc. |
5bf135a7 NC |
296 | |
297 | Copying and distribution of this file, with or without modification, | |
298 | are permitted in any medium without royalty provided the copyright | |
299 | notice and this notice are preserved. |