xref: /dflybsd-src/contrib/binutils-2.27/gas/README (revision e656dc90e3d65d744d534af2f5ea88cf8101ebcf)
1*a9fa9459Szrj		README for GAS
2*a9fa9459Szrj
3*a9fa9459SzrjA number of things have changed since version 1 and the wonderful
4*a9fa9459Szrjworld of gas looks very different.  There's still a lot of irrelevant
5*a9fa9459Szrjgarbage lying around that will be cleaned up in time.  Documentation
6*a9fa9459Szrjis scarce, as are logs of the changes made since the last gas release.
7*a9fa9459SzrjMy apologies, and I'll try to get something useful.
8*a9fa9459Szrj
9*a9fa9459SzrjUnpacking and Installation - Summary
10*a9fa9459Szrj====================================
11*a9fa9459Szrj
12*a9fa9459SzrjSee ../binutils/README.
13*a9fa9459Szrj
14*a9fa9459SzrjTo build just the assembler, make the target all-gas.
15*a9fa9459Szrj
16*a9fa9459SzrjDocumentation
17*a9fa9459Szrj=============
18*a9fa9459Szrj
19*a9fa9459SzrjThe GAS release includes texinfo source for its manual, which can be processed
20*a9fa9459Szrjinto `info' or `dvi' forms.
21*a9fa9459Szrj
22*a9fa9459SzrjThe DVI form is suitable for printing or displaying; the commands for doing
23*a9fa9459Szrjthis vary from system to system.  On many systems, `lpr -d' will print a DVI
24*a9fa9459Szrjfile.  On others, you may need to run a program such as `dvips' to convert the
25*a9fa9459SzrjDVI file into a form your system can print.
26*a9fa9459Szrj
27*a9fa9459SzrjIf you wish to build the DVI file, you will need to have TeX installed on your
28*a9fa9459Szrjsystem.  You can rebuild it by typing:
29*a9fa9459Szrj
30*a9fa9459Szrj	cd gas/doc
31*a9fa9459Szrj	make as.dvi
32*a9fa9459Szrj
33*a9fa9459SzrjThe Info form is viewable with the GNU Emacs `info' subsystem, or the
34*a9fa9459Szrjstand-alone `info' program, available as part of the GNU Texinfo distribution.
35*a9fa9459SzrjTo build the info files, you will need the `makeinfo' program.  Type:
36*a9fa9459Szrj
37*a9fa9459Szrj	cd gas/doc
38*a9fa9459Szrj	make info
39*a9fa9459Szrj
40*a9fa9459SzrjSpecifying names for hosts and targets
41*a9fa9459Szrj======================================
42*a9fa9459Szrj
43*a9fa9459Szrj   The specifications used for hosts and targets in the `configure'
44*a9fa9459Szrjscript are based on a three-part naming scheme, but some short
45*a9fa9459Szrjpredefined aliases are also supported.  The full naming scheme encodes
46*a9fa9459Szrjthree pieces of information in the following pattern:
47*a9fa9459Szrj
48*a9fa9459Szrj     ARCHITECTURE-VENDOR-OS
49*a9fa9459Szrj
50*a9fa9459Szrj   For example, you can use the alias `sun4' as a HOST argument or in a
51*a9fa9459Szrj`--target=TARGET' option.  The equivalent full name is
52*a9fa9459Szrj`sparc-sun-sunos4'.
53*a9fa9459Szrj
54*a9fa9459Szrj   The `configure' script accompanying GAS does not provide any query
55*a9fa9459Szrjfacility to list all supported host and target names or aliases.
56*a9fa9459Szrj`configure' calls the Bourne shell script `config.sub' to map
57*a9fa9459Szrjabbreviations to full names; you can read the script, if you wish, or
58*a9fa9459Szrjyou can use it to test your guesses on abbreviations--for example:
59*a9fa9459Szrj
60*a9fa9459Szrj     % sh config.sub i386v
61*a9fa9459Szrj     i386-unknown-sysv
62*a9fa9459Szrj     % sh config.sub i786v
63*a9fa9459Szrj     Invalid configuration `i786v': machine `i786v' not recognized
64*a9fa9459Szrj
65*a9fa9459Szrj
66*a9fa9459Szrj`configure' options
67*a9fa9459Szrj===================
68*a9fa9459Szrj
69*a9fa9459Szrj   Here is a summary of the `configure' options and arguments that are
70*a9fa9459Szrjmost often useful for building GAS.  `configure' also has several other
71*a9fa9459Szrjoptions not listed here.
72*a9fa9459Szrj
73*a9fa9459Szrj     configure [--help]
74*a9fa9459Szrj               [--prefix=DIR]
75*a9fa9459Szrj               [--srcdir=PATH]
76*a9fa9459Szrj               [--host=HOST]
77*a9fa9459Szrj               [--target=TARGET]
78*a9fa9459Szrj               [--with-OPTION]
79*a9fa9459Szrj               [--enable-OPTION]
80*a9fa9459Szrj
81*a9fa9459SzrjYou may introduce options with a single `-' rather than `--' if you
82*a9fa9459Szrjprefer; but you may abbreviate option names if you use `--'.
83*a9fa9459Szrj
84*a9fa9459Szrj`--help'
85*a9fa9459Szrj     Print a summary of the options to `configure', and exit.
86*a9fa9459Szrj
87*a9fa9459Szrj`-prefix=DIR'
88*a9fa9459Szrj     Configure the source to install programs and files under directory
89*a9fa9459Szrj     `DIR'.
90*a9fa9459Szrj
91*a9fa9459Szrj`--srcdir=PATH'
92*a9fa9459Szrj     Look for the package's source code in directory DIR.  Usually
93*a9fa9459Szrj     `configure' can determine that directory automatically.
94*a9fa9459Szrj
95*a9fa9459Szrj`--host=HOST'
96*a9fa9459Szrj     Configure GAS to run on the specified HOST.  Normally the
97*a9fa9459Szrj     configure script can figure this out automatically.
98*a9fa9459Szrj
99*a9fa9459Szrj     There is no convenient way to generate a list of all available
100*a9fa9459Szrj     hosts.
101*a9fa9459Szrj
102*a9fa9459Szrj`--target=TARGET'
103*a9fa9459Szrj     Configure GAS for cross-assembling programs for the specified
104*a9fa9459Szrj     TARGET.  Without this option, GAS is configured to assemble .o files
105*a9fa9459Szrj     that run on the same machine (HOST) as GAS itself.
106*a9fa9459Szrj
107*a9fa9459Szrj     There is no convenient way to generate a list of all available
108*a9fa9459Szrj     targets.
109*a9fa9459Szrj
110*a9fa9459Szrj`--enable-OPTION'
111*a9fa9459Szrj     These flags tell the program or library being configured to
112*a9fa9459Szrj     configure itself differently from the default for the specified
113*a9fa9459Szrj     host/target combination.  See below for a list of `--enable'
114*a9fa9459Szrj     options recognized in the gas distribution.
115*a9fa9459Szrj
116*a9fa9459Szrj`configure' accepts other options, for compatibility with configuring
117*a9fa9459Szrjother GNU tools recursively; but these are the only options that affect
118*a9fa9459SzrjGAS or its supporting libraries.
119*a9fa9459Szrj
120*a9fa9459SzrjThe `--enable' options recognized by software in the gas distribution are:
121*a9fa9459Szrj
122*a9fa9459Szrj`--enable-targets=...'
123*a9fa9459Szrj     This causes one or more specified configurations to be added to those for
124*a9fa9459Szrj     which BFD support is compiled.  Currently gas cannot use any format other
125*a9fa9459Szrj     than its compiled-in default, so this option is not very useful.
126*a9fa9459Szrj
127*a9fa9459Szrj`--enable-bfd-assembler'
128*a9fa9459Szrj     This causes the assembler to use the new code being merged into it to use
129*a9fa9459Szrj     BFD data structures internally, and use BFD for writing object files.
130*a9fa9459Szrj     For most targets, this isn't supported yet.  For most targets where it has
131*a9fa9459Szrj     been done, it's already the default.  So generally you won't need to use
132*a9fa9459Szrj     this option.
133*a9fa9459Szrj
134*a9fa9459SzrjCompiler Support Hacks
135*a9fa9459Szrj======================
136*a9fa9459Szrj
137*a9fa9459SzrjOn a few targets, the assembler has been modified to support a feature
138*a9fa9459Szrjthat is potentially useful when assembling compiler output, but which
139*a9fa9459Szrjmay confuse assembly language programmers.  If assembler encounters a
140*a9fa9459Szrj.word pseudo-op of the form symbol1-symbol2 (the difference of two
141*a9fa9459Szrjsymbols), and the difference of those two symbols will not fit in 16
142*a9fa9459Szrjbits, the assembler will create a branch around a long jump to
143*a9fa9459Szrjsymbol1, and insert this into the output directly before the next
144*a9fa9459Szrjlabel: The .word will (instead of containing garbage, or giving an
145*a9fa9459Szrjerror message) contain (the address of the long jump)-symbol2.  This
146*a9fa9459Szrjallows the assembler to assemble jump tables that jump to locations
147*a9fa9459Szrjvery far away into code that works properly.  If the next label is
148*a9fa9459Szrjmore than 32K away from the .word, you lose (silently); RMS claims
149*a9fa9459Szrjthis will never happen.  If the -K option is given, you will get a
150*a9fa9459Szrjwarning message when this happens.
151*a9fa9459Szrj
152*a9fa9459Szrj
153*a9fa9459SzrjREPORTING BUGS IN GAS
154*a9fa9459Szrj=====================
155*a9fa9459Szrj
156*a9fa9459SzrjBugs in gas should be reported to:
157*a9fa9459Szrj
158*a9fa9459Szrj   bug-binutils@gnu.org.
159*a9fa9459Szrj
160*a9fa9459SzrjThey may be cross-posted to gcc-bugs@gnu.org if they affect the use of
161*a9fa9459Szrjgas with gcc.  They should not be reported just to gcc-bugs, since not
162*a9fa9459Szrjall of the maintainers read that list.
163*a9fa9459Szrj
164*a9fa9459SzrjSee ../binutils/README for what we need in a bug report.
165*a9fa9459Szrj
166*a9fa9459SzrjCopyright (C) 2012-2016 Free Software Foundation, Inc.
167*a9fa9459Szrj
168*a9fa9459SzrjCopying and distribution of this file, with or without modification,
169*a9fa9459Szrjare permitted in any medium without royalty provided the copyright
170*a9fa9459Szrjnotice and this notice are preserved.
171