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