Initial revision
This commit is contained in:
Steve Chamberlain
parent
d51d16c8e6
commit
80d29884b8
|
|
@ -0,0 +1,56 @@
|
|||
.SUFFIXES: .texi .o .c .h .p .ip
|
||||
VPATH=..
|
||||
.c.texi:
|
||||
scanit $< $@
|
||||
|
||||
.h.texi:
|
||||
scanit $< $@
|
||||
|
||||
.c.p:
|
||||
scanph $< $@
|
||||
|
||||
.h.p:
|
||||
scanph $< $@
|
||||
|
||||
.c.ip:
|
||||
scanph -i $< $@
|
||||
|
||||
|
||||
DOCFILES = syms.texi bfd.texi cache.texi \
|
||||
format.texi section.texi archive.texi \
|
||||
core.texi libbfd.texi archures.texi \
|
||||
reloc.texi opncls.texi targets.texi \
|
||||
aoutx.texi coffcode.texi cache.texi
|
||||
|
||||
PROTOS = opncls.p archures.p libbfd.p \
|
||||
section.p syms.p bfd.p \
|
||||
archive.p reloc.p targets.p \
|
||||
format.p coffcode.p core.p
|
||||
|
||||
IPROTOS = cache.ip libbfd.ip reloc.ip
|
||||
|
||||
docs: $(DOCFILES)
|
||||
|
||||
protos: $(PROTOS) $(IPROTOS)
|
||||
sed -f intobfd bfd-in.h > bfd.h
|
||||
sed -f tolibbfd libbfd-in.h > libbfd.h
|
||||
sed -f tolibcoff libcoff-in.h > libcoff.h
|
||||
|
||||
|
||||
|
||||
clean:
|
||||
rm -f $(PROTOS) *.p *.ip *.h bfd.?? $(DOCFILES) bfd.dvi bfd.ps *~* *# bfd.???
|
||||
|
||||
bfd.info: $(DOCFILES) bfd.texinfo
|
||||
makeinfo +no-validate bfd.texinfo
|
||||
|
||||
bfd.dvi: $(DOCFILES) bfd.texinfo
|
||||
tex bfd.texinfo
|
||||
texindex bfd.??
|
||||
tex bfd.texinfo
|
||||
|
||||
bfd.ps: bfd.dvi
|
||||
dvips bfd -o
|
||||
|
||||
quickdoc: $(DSRC) docs
|
||||
tex bfd.texinfo
|
||||
|
|
@ -0,0 +1,12 @@
|
|||
# NOTE: BEGIN pattern gives errors if other than 1st line;
|
||||
# END ditto if other than last.
|
||||
BEGIN { print "@c ------------------------------START TEXT FROM " FILENAME }
|
||||
#
|
||||
# Keep /*doc* blocks (terminated by either */ or *-*/)
|
||||
/^\/\*doc\*/,/^\*\/|^\*-\*\//
|
||||
#
|
||||
# Also keep two kinds of /*proto blocks
|
||||
/^\/\*proto\*/,/^\*\/|^\*-\*\//
|
||||
/^\/\*proto-internal\*/,/^\*\/|^\*-\*\//
|
||||
#
|
||||
END { print "@c ------------------------------END TEXT FROM " FILENAME }
|
||||
|
|
@ -0,0 +1,8 @@
|
|||
# Awk filter, 1st filter for BFD internal prototype file extraction
|
||||
#
|
||||
# keep /*proto-internal blocks
|
||||
/^\/\*proto-internal\*/,/^\*\/|^\*-\*\//
|
||||
#
|
||||
# Apparent bug in sed can discard last line in some situations; therefore
|
||||
# make last line harmless.
|
||||
END { print "\n" }
|
||||
|
|
@ -0,0 +1,8 @@
|
|||
# Awk filter, 1st filter for BFD prototype file extraction
|
||||
#
|
||||
# keep /*proto blocks
|
||||
/^\/\*proto\*/,/^\*\/|^\*-\*\//
|
||||
#
|
||||
# Apparent bug in sed can discard last line in some situations; therefore
|
||||
# make last line harmless.
|
||||
END { print "\n" }
|
||||
|
|
@ -0,0 +1,430 @@
|
|||
\input texinfo
|
||||
@setfilename bfdinfo
|
||||
@c $Id$
|
||||
@synindex ky cp
|
||||
@ifinfo
|
||||
This file documents the BFD library.
|
||||
|
||||
Copyright (C) 1991 Free Software Foundation, Inc.
|
||||
|
||||
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.
|
||||
|
||||
@ignore
|
||||
Permission is granted to process this file through Tex and print the
|
||||
results, provided the printed document carries copying permission
|
||||
notice identical to this one except for the removal of this paragraph
|
||||
(this paragraph not being relevant to the printed manual).
|
||||
|
||||
@end ignore
|
||||
Permission is granted to copy and distribute modified versions of this
|
||||
manual under the conditions for verbatim copying, subject to the terms
|
||||
of the GNU General Public License, which includes the provision 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.
|
||||
@end ifinfo
|
||||
@iftex
|
||||
@c@finalout
|
||||
@setchapternewpage on
|
||||
@c@setchapternewpage odd
|
||||
@settitle LIB BFD, the Binary File Descriptor Library
|
||||
@titlepage
|
||||
@title{libbfd}
|
||||
@subtitle{The Binary File Descriptor Library}
|
||||
@sp 1
|
||||
@subtitle First Edition---BFD version < 2.0
|
||||
@subtitle April 1991
|
||||
@author {Steve Chamberlain}
|
||||
@author {Cygnus Support}
|
||||
@page
|
||||
|
||||
@tex
|
||||
\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
|
||||
\xdef\manvers{\$Revision$} % For use in headers, footers too
|
||||
{\parskip=0pt
|
||||
\hfill Cygnus Support\par
|
||||
\hfill steve\@cygnus.com\par
|
||||
\hfill {\it BFD}, \manvers\par
|
||||
\hfill \TeX{}info \texinfoversion\par
|
||||
}
|
||||
\global\parindent=0pt % Steve likes it this way
|
||||
@end tex
|
||||
|
||||
@vskip 0pt plus 1filll
|
||||
Copyright @copyright{} 1991 Free Software Foundation, Inc.
|
||||
|
||||
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, subject to the terms
|
||||
of the GNU General Public License, which includes the provision 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.
|
||||
@end titlepage
|
||||
@end iftex
|
||||
|
||||
@node Top, Overview, (dir), (dir)
|
||||
@ifinfo
|
||||
This file documents the binary file descriptor library libbfd.
|
||||
@end ifinfo
|
||||
|
||||
@menu
|
||||
* Overview:: Overview of BFD
|
||||
* History:: History of BFD
|
||||
* Backends:: Backends
|
||||
* Porting:: Porting
|
||||
* Future:: Future
|
||||
* Index:: Index
|
||||
|
||||
BFD body:
|
||||
* Memory usage::
|
||||
* Sections::
|
||||
* Symbols::
|
||||
* Archives::
|
||||
* Formats::
|
||||
* Relocations::
|
||||
* Core Files::
|
||||
* Targets::
|
||||
* Architecturs::
|
||||
* Opening and Closing::
|
||||
* Internal::
|
||||
* File Caching::
|
||||
|
||||
BFD backends:
|
||||
* a.out backends::
|
||||
* coff backends::
|
||||
@end menu
|
||||
|
||||
@node Overview, History, Top, Top
|
||||
@chapter Introduction
|
||||
@cindex BFD
|
||||
@cindex what is it?
|
||||
Simply put, BFD is a package which allows applications to use the
|
||||
same routines to operate on object files whatever the object file
|
||||
format. A different object file format can be supported simply by
|
||||
creating a new BFD back end and adding it to the library.
|
||||
|
||||
BFD is split into two parts; the front end and the many back ends.
|
||||
@itemize @bullet
|
||||
@item The front end of BFD provides the interface to the user. It manages
|
||||
memory, and various canonical data structures. The front end also
|
||||
decides which back end to use, and when to call back end routines.
|
||||
@item The back ends provide BFD its view of the real world. Each back
|
||||
end provides a set of calls which the BFD front end can use to maintain
|
||||
its canonical form. The back ends also may keep around information for
|
||||
their own use, for greater efficiency.
|
||||
@end itemize
|
||||
@node History, How It Works, Overview,Top
|
||||
@section History
|
||||
|
||||
One spur behind BFD was the desire, on the part of the GNU 960 team at
|
||||
Intel Oregon, for interoperability of applications on their COFF and
|
||||
b.out file formats. Cygnus was providing GNU support for the team, and
|
||||
Cygnus was contracted to provide the required functionality.
|
||||
|
||||
The name came from a conversation David Wallace was having with Richard
|
||||
Stallman about the library: RMS said that it would be quite hard---David
|
||||
said ``BFD''. Stallman was right, but the name stuck.
|
||||
|
||||
At the same time, Ready Systems wanted much the same thing, but for
|
||||
different object file formats: IEEE-695, Oasys, Srecords, a.out and 68k
|
||||
coff.
|
||||
|
||||
BFD was first implemented by Steve Chamberlain (steve@@cygnus.com),
|
||||
John Gilmore (gnu@@cygnus.com), K. Richard Pixley (rich@@cygnus.com) and
|
||||
David Wallace (gumby@@cygnus.com) at Cygnus Support in Palo Alto,
|
||||
California.
|
||||
|
||||
@node How It Works, History, Porting, Top
|
||||
@section How It Works
|
||||
|
||||
To use the library, include @code{bfd.h} and link with @code{libbfd.a}.
|
||||
|
||||
BFD provides a common interface to the parts of an object file
|
||||
for a calling application.
|
||||
|
||||
When an application sucessfully opens a target file (object, archive or
|
||||
whatever) a pointer to an internal structure is returned. This pointer
|
||||
points to a structure called @code{bfd}, described in
|
||||
@code{include/bfd.h}. Our convention is to call this pointer a BFD, and
|
||||
instances of it within code @code{abfd}. All operations on
|
||||
the target object file are applied as methods to the BFD. The mapping is
|
||||
defined within @code{bfd.h} in a set of macros, all beginning
|
||||
@samp{bfd}_.
|
||||
|
||||
For example, this sequence would do what you would probably expect:
|
||||
return the number of sections in an object file attached to a BFD
|
||||
@code{abfd}.
|
||||
|
||||
@lisp
|
||||
@cartouche
|
||||
#include "bfd.h"
|
||||
|
||||
unsigned int number_of_sections(abfd)
|
||||
bfd *abfd;
|
||||
@{
|
||||
return bfd_count_sections(abfd);
|
||||
@}
|
||||
@end cartouche
|
||||
@end lisp
|
||||
|
||||
The abstraction used within BFD is that an object file has a header,
|
||||
a number of sections containing raw data, a set of relocations, and some
|
||||
symbol information. Also, BFDs opened for archives have the
|
||||
additional attribute of an index and contain subordinate BFDs. This approach is
|
||||
fine for a.out and coff, but loses efficiency when applied to formats
|
||||
such as S-records and IEEE-695.
|
||||
|
||||
@section What BFD Version 1 Can Do
|
||||
As different information from the the object files is required,
|
||||
BFD reads from different sections of the file and processes them.
|
||||
For example a very common operation for the linker is processing symbol
|
||||
tables. Each BFD back end provides a routine for converting
|
||||
between the object file's representation of symbols and an internal
|
||||
canonical format. When the linker asks for the symbol table of an object
|
||||
file, it calls through the memory pointer to the relevant BFD
|
||||
back end routine which reads and converts the table into a canonical
|
||||
form. The linker then operates upon the canonical form. When the link is
|
||||
finished and the linker writes the output file's symbol table,
|
||||
another BFD back end routine is called which takes the newly
|
||||
created symbol table and converts it into the chosen output format.
|
||||
|
||||
@node BFD information loss, Mechanism, BFD outline, BFD
|
||||
@subsection Information Loss
|
||||
@emph{Some information is lost due to the nature of the file format.} The output targets
|
||||
supported by BFD do not provide identical facilities, and
|
||||
information which may be described in one form has nowhere to go in
|
||||
another format. One example of this is alignment information in
|
||||
@code{b.out}. There is nowhere in an @code{a.out} format file to store
|
||||
alignment information on the contained data, so when a file is linked
|
||||
from @code{b.out} and an @code{a.out} image is produced, alignment
|
||||
information will not propagate to the output file. (The linker will
|
||||
still use the alignment information internally, so the link is performed
|
||||
correctly).
|
||||
|
||||
Another example is COFF section names. COFF files may contain an
|
||||
unlimited number of sections, each one with a textual section name. If
|
||||
the target of the link is a format which does not have many sections (eg
|
||||
@code{a.out}) or has sections without names (eg the Oasys format) the
|
||||
link cannot be done simply. You can circumvent this problem by
|
||||
describing the desired input-to-output section mapping with the linker command
|
||||
language.
|
||||
|
||||
@emph{Information can be lost during canonicalization.} The BFD
|
||||
internal canonical form of the external formats is not exhaustive; there
|
||||
are structures in input formats for which there is no direct
|
||||
representation internally. This means that the BFD back ends
|
||||
cannot maintain all possible data richness through the transformation
|
||||
between external to internal and back to external formats.
|
||||
|
||||
This limitation is only a problem when an application reads one
|
||||
format and writes another. Each BFD back end is responsible for
|
||||
maintaining as much data as possible, and the internal BFD
|
||||
canonical form has structures which are opaque to the BFD core,
|
||||
and exported only to the back ends. When a file is read in one format,
|
||||
the canonical form is generated for BFD and the application. At the
|
||||
same time, the back end saves away any information which may otherwise
|
||||
be lost. If the data is then written back in the same format, the back
|
||||
end routine will be able to use the canonical form provided by the
|
||||
BFD core as well as the information it prepared earlier. Since
|
||||
there is a great deal of commonality between back ends, this mechanism
|
||||
is very useful. There is no information lost for this reason when
|
||||
linking or copying big endian COFF to little endian COFF, or @code{a.out} to
|
||||
@code{b.out}. When a mixture of formats is linked, the information is
|
||||
only lost from the files whose format differs from the destination.
|
||||
|
||||
@node Mechanism, , BFD information loss, BFD
|
||||
@subsection Mechanism
|
||||
The greatest potential for loss of information is when there is least
|
||||
overlap between the information provided by the source format, that
|
||||
stored by the canonical format, and the information needed by the
|
||||
destination format. A brief description of the canonical form may help
|
||||
you appreciate what kinds of data you can count on preserving across
|
||||
conversions.
|
||||
@cindex BFD canonical format
|
||||
@cindex internal object-file format
|
||||
|
||||
@table @emph
|
||||
@item files
|
||||
Information on target machine architecture, particular implementation
|
||||
and format type are stored on a per-file basis. Other information
|
||||
includes a demand pageable bit and a write protected bit. Note that
|
||||
information like Unix magic numbers is not stored here---only the magic
|
||||
numbers' meaning, so a @code{ZMAGIC} file would have both the demand
|
||||
pageable bit and the write protected text bit set. The byte order of
|
||||
the target is stored on a per-file basis, so that big- and little-endian
|
||||
object files may be linked with one another.
|
||||
@c FIXME: generalize above from "link"?
|
||||
|
||||
@item sections
|
||||
Each section in the input file contains the name of the section, the
|
||||
original address in the object file, various flags, size and alignment
|
||||
information and pointers into other BFD data structures.
|
||||
|
||||
@item symbols
|
||||
Each symbol contains a pointer to the object file which originally
|
||||
defined it, its name, its value, and various flag bits. When a
|
||||
BFD back end reads in a symbol table, the back end relocates all
|
||||
symbols to make them relative to the base of the section where they were
|
||||
defined. This ensures that each symbol points to its containing
|
||||
section. Each symbol also has a varying amount of hidden data to contain
|
||||
private data for the BFD back end. Since the symbol points to the
|
||||
original file, the private data format for that symbol is accessible.
|
||||
@code{gld} can operate on a collection of symbols of wildly different
|
||||
formats without problems.
|
||||
|
||||
Normal global and simple local symbols are maintained on output, so an
|
||||
output file (no matter its format) will retain symbols pointing to
|
||||
functions and to global, static, and common variables. Some symbol
|
||||
information is not worth retaining; in @code{a.out} type information is
|
||||
stored in the symbol table as long symbol names. This information would
|
||||
be useless to most COFF debuggers; the linker has command line switches
|
||||
to allow users to throw it away.
|
||||
|
||||
There is one word of type information within the symbol, so if the
|
||||
format supports symbol type information within symbols (for example COFF,
|
||||
IEEE, Oasys) and the type is simple enough to fit within one word
|
||||
(nearly everything but aggregates) the information will be preserved.
|
||||
|
||||
@item relocation level
|
||||
Each canonical BFD relocation record contains a pointer to the symbol to
|
||||
relocate to, the offset of the data to relocate, the section the data
|
||||
is in and a pointer to a relocation type descriptor. Relocation is
|
||||
performed effectively by message passing through the relocation type
|
||||
descriptor and symbol pointer. It allows relocations to be performed
|
||||
on output data using a relocation method only available in one of the
|
||||
input formats. For instance, Oasys provides a byte relocation format.
|
||||
A relocation record requesting this relocation type would point
|
||||
indirectly to a routine to perform this, so the relocation may be
|
||||
performed on a byte being written to a COFF file, even though 68k COFF
|
||||
has no such relocation type.
|
||||
|
||||
@item line numbers
|
||||
Object formats can contain, for debugging purposes, some form of mapping
|
||||
between symbols, source line numbers, and addresses in the output file.
|
||||
These addresses have to be relocated along with the symbol information.
|
||||
Each symbol with an associated list of line number records points to the
|
||||
first record of the list. The head of a line number list consists of a
|
||||
pointer to the symbol, which allows divination of the address of the
|
||||
function whose line number is being described. The rest of the list is
|
||||
made up of pairs: offsets into the section and line numbers. Any format
|
||||
which can simply derive this information can pass it successfully
|
||||
between formats (COFF, IEEE and Oasys).
|
||||
@end table
|
||||
|
||||
@c FIXME: what is this line about? Do we want introductory remarks
|
||||
@c FIXME... on back ends? commented out for now.
|
||||
@c What is a backend
|
||||
@node BFD front end, BFD back end, Mechanism, Top
|
||||
@chapter BFD front end
|
||||
@include bfd.texi
|
||||
|
||||
@node Memory Usage, Sections, bfd, Top
|
||||
@section Memory Usage
|
||||
BFD keeps all its internal structures in obstacks. There is one obstack
|
||||
per open BFD file, into which the current state is stored. When a BFD is
|
||||
closed, the obstack is deleted, and so everything which has been
|
||||
allocated by libbfd for the closing file will be thrown away.
|
||||
|
||||
BFD will not free anything created by an application, but pointers into
|
||||
@code{bfd} structures will be invalidated on a @code{bfd_close}; for example,
|
||||
after a @code{bfd_close} the vector passed to
|
||||
@code{bfd_canonicalize_symtab} will still be around, since it has been
|
||||
allocated by the application, but the data that it pointed to will be
|
||||
lost.
|
||||
|
||||
The general rule is not to close a BFD until all operations dependent
|
||||
upon data from the BFD have been completed, or all the data from within
|
||||
the file has been copied. To help with the management of memory, there is a function
|
||||
(@code{bfd_alloc_size}) which returns the number of bytes in obstacks
|
||||
associated with the supplied BFD. This could be used to select the
|
||||
greediest open BFD, close it to reclaim the memory, perform some
|
||||
operation and reopen the BFD again, to get a fresh copy of the data structures.
|
||||
|
||||
@node Sections,Symbols ,Memory Usage, Top
|
||||
@include section.texi
|
||||
|
||||
@node Symbols, Archives ,Sections, To
|
||||
@include syms.texi
|
||||
|
||||
@node Archives, Formats, Symbols, Top
|
||||
@include archive.texi
|
||||
|
||||
@node Formats, Relocations, Archives, Top
|
||||
@include format.texi
|
||||
|
||||
@node Relocations, Core Files,Formats, Top
|
||||
@include reloc.texi
|
||||
|
||||
@node Core Files, Targets, Relocations, Top
|
||||
@include core.texi
|
||||
|
||||
@node Targets, Architectures, Core Files, Top
|
||||
@include targets.texi
|
||||
|
||||
@node Architectures, Opening and Closing, Targets, Top
|
||||
@include archures.texi
|
||||
|
||||
@node Opening and Closing, Internal, Architectures, Top
|
||||
@include opncls.texi
|
||||
|
||||
@node Internal, File Caching, Opening and Closing, Top
|
||||
@include libbfd.texi
|
||||
|
||||
@node File Caching, Top, Internal, Top
|
||||
@include cache.texi
|
||||
|
||||
@chapter BFD back end
|
||||
@node BFD back end, ,BFD front end, Top
|
||||
@menu
|
||||
* What to put where
|
||||
* a.out backends::
|
||||
* coff backends::
|
||||
* oasys backend::
|
||||
* ieee backend::
|
||||
* srecord backend::
|
||||
@end menu
|
||||
@node What to Put Where, aout backends, BFD back end, BFD back end
|
||||
All of BFD lives in one directory.
|
||||
|
||||
@node aout backends, coff backends, What to Put Where, BFD back end
|
||||
@include aoutx.texi
|
||||
|
||||
@node coff backends, oasys backends, aout backends, BFD back end
|
||||
@include coffcode.texi
|
||||
|
||||
@node Index, , BFD, Top
|
||||
@unnumbered Function Index
|
||||
@printindex fn
|
||||
@unnumbered Index
|
||||
@printindex cp
|
||||
|
||||
@tex
|
||||
% I think something like @colophon should be in texinfo. In the
|
||||
% meantime:
|
||||
\long\def\colophon{\hbox to0pt{}\vfill
|
||||
\centerline{The body of this manual is set in}
|
||||
\centerline{\fontname\tenrm,}
|
||||
\centerline{with headings in {\bf\fontname\tenbf}}
|
||||
\centerline{and examples in {\tt\fontname\tentt}.}
|
||||
\centerline{{\it\fontname\tenit\/} and}
|
||||
\centerline{{\sl\fontname\tensl\/}}
|
||||
\centerline{are used for emphasis.}\vfill}
|
||||
\page\colophon
|
||||
% Blame: pesch@cygnus.com, 28mar91.
|
||||
@end tex
|
||||
|
||||
|
||||
@contents
|
||||
@bye
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,8 @@
|
|||
# sed script for BFD header files
|
||||
# Merge adjacent blank lines. Loop til no change.
|
||||
:blin
|
||||
/^$/,/^ *[^ ]*.*$/{
|
||||
/^$/N
|
||||
s/^ *\n *$//
|
||||
}
|
||||
t blin
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
#
|
||||
# Locate and coalesce adjacent comments
|
||||
/\*\/$/N
|
||||
s/\*\/\n\/\*/\
|
||||
/
|
||||
|
|
@ -0,0 +1,16 @@
|
|||
# blank-line activity:
|
||||
# Merge adjacent blank lines. Loop til no change.
|
||||
:blin
|
||||
/^$/,/^ *[^ ]*.*$/{
|
||||
/^$/N
|
||||
s/^ *\n *$//
|
||||
}
|
||||
t blin
|
||||
#
|
||||
/^$/,/^ *[^ ]*.*$/{
|
||||
/^$/N
|
||||
# Transpose <blank line> <end comment>
|
||||
/^ *\n\*\/$/c\
|
||||
*\/\
|
||||
|
||||
}
|
||||
|
|
@ -0,0 +1,14 @@
|
|||
# SED script for preprocessing embedded doc from source (S. Chamberlain markup)
|
||||
# Final pass; cleanup work is done here.
|
||||
#
|
||||
# Within examples, make '{' and '}' printable:
|
||||
/^@lisp$/,/^@end lisp$/s/{/@{/
|
||||
/^@lisp$/,/^@end lisp$/s/}/@}/
|
||||
/^@example$/,/^@end example$/s/{/@{/
|
||||
/^@example$/,/^@end example$/s/}/@}/
|
||||
#
|
||||
# Delete empty @findex and @subsubsection entries (resulting from *proto*
|
||||
# with no further text on same line, in middle pass)
|
||||
/^@findex $/d
|
||||
/^@subsubsection @code{}/d
|
||||
#
|
||||
|
|
@ -0,0 +1,12 @@
|
|||
# SED script for preprocessing embedded headers from C source comments
|
||||
# (S. Chamberlain markup)
|
||||
# beginning of many passes of cleanup work
|
||||
#
|
||||
# Delete empty comment blocks
|
||||
/^\/\*$/N
|
||||
/^\/\*\n\*\/ *$/d
|
||||
#
|
||||
# Locate and coalesce adjacent comments
|
||||
/\*\/$/N
|
||||
s/\*\/\n\/\*/\
|
||||
/
|
||||
|
|
@ -0,0 +1,8 @@
|
|||
# Merge adjacent blank lines. Loop til no change.
|
||||
:blin
|
||||
/^$/,/^ *[^ ]*.*$/{
|
||||
/^$/N
|
||||
s/^ *\n *$//
|
||||
}
|
||||
t blin
|
||||
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
# SED script for preprocessing embedded doc from source (S. Chamberlain markup)
|
||||
# Locate and coalesce adjacent @example blocks
|
||||
/^@end example/N
|
||||
/^@end example\n@example$/d
|
||||
|
|
@ -0,0 +1,11 @@
|
|||
/\/\*:archive.c\*\//r archive.p
|
||||
/\/\*:archures.c\*\//r archures.p
|
||||
/\/\*:bfd.c\*\//r bfd.p
|
||||
/\/\*:core.c\*\//r core.p
|
||||
/\/\*:format.c\*\//r format.p
|
||||
/\/\*:libbfd.c\*\//r libbfd.p
|
||||
/\/\*:opncls.c\*\//r opncls.p
|
||||
/\/\*:reloc.c\*\//r reloc.p
|
||||
/\/\*:section.c\*\//r section.p
|
||||
/\/\*:syms.c\*\//r syms.p
|
||||
/\/\*:targets.c\*\//r targets.p
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
# SED script for preprocessing embedded headers from C source comments
|
||||
# Locate and coalesce adjacent comments
|
||||
/\*\/$/N
|
||||
s/\*\/\n\/\*/\
|
||||
/
|
||||
|
|
@ -0,0 +1,8 @@
|
|||
# sed script for BFD header files:
|
||||
# Transpose <blank line> <end comment>
|
||||
/^$/,/^ *[^ ]*.*$/{
|
||||
/^$/N
|
||||
/^ *\n\*\/$/c\
|
||||
*\/\
|
||||
|
||||
}
|
||||
|
|
@ -0,0 +1,25 @@
|
|||
#!/bin/sh
|
||||
# Script to coordinate parsing of S. Chamberlain source-embedded
|
||||
# documentation markup language.
|
||||
|
||||
# Four passes:
|
||||
# 1) awk discards lines not intended for docn, and marks blocks of
|
||||
# text with comments identifying source file;
|
||||
# 2) first sed pass interprets Chamberlain markup;
|
||||
# 3) second sed pass does cleanup that involves merging lines
|
||||
# 4) third sed pass does remaining cleans up---making {}
|
||||
# printable within examples, and eliminating empty index entries and
|
||||
# headings.
|
||||
#Third and second sed passes are separate because order of execution is hard
|
||||
#to control otherwise, making one or another of the things involving @example
|
||||
#inoperative.
|
||||
|
||||
base=`echo $1 | cut -d '.' -f 1`
|
||||
out=`echo $2 | cut -d '.' -f 1`
|
||||
|
||||
awk -f awkscan $1 | \
|
||||
sed -f sedscript | \
|
||||
sed -f unPROTO | \
|
||||
sed -f exmerge | \
|
||||
sed -f exfilter >$out.texi
|
||||
|
||||
|
|
@ -0,0 +1,26 @@
|
|||
#!/bin/sh
|
||||
# Script to coordinate parsing of S. Chamberlain source-embedded
|
||||
# header-file markup language.
|
||||
|
||||
# '-i' option means use *proto-internal* segments, else just *proto*
|
||||
SFX=p
|
||||
if [ $1 = "-i" ]; then
|
||||
SFX=ip
|
||||
shift
|
||||
fi
|
||||
|
||||
base=`echo $1 | cut -d '.' -f 1`
|
||||
out=`echo $2 | cut -d '.' -f 1`
|
||||
|
||||
# passes:
|
||||
# 1) awk discards lines not intended for header, and marks blocks of
|
||||
# text with comments identifying source file;
|
||||
# 2) first sed pass interprets Chamberlain markup;
|
||||
# 3) further sed passes clean up---merging adjacent comments etc.
|
||||
|
||||
awk -f awkscan-$SFX $1 |\
|
||||
sed -f sedscript-p |\
|
||||
sed -f mergecom-p |\
|
||||
sed -f startcom-p |\
|
||||
sed -f blins-p |\
|
||||
sed -f movecom-p >$out.$SFX
|
||||
|
|
@ -0,0 +1,85 @@
|
|||
# SED script for preprocessing embedded doc from source (S. Chamberlain markup)
|
||||
# middle pass; most of the work is done here.
|
||||
#
|
||||
# First, get rid of /*doc* markers; they've done their job in the first pass.
|
||||
/^\/\*doc\*/d
|
||||
#
|
||||
# /*proto* markers may be optionally followed by a *i-style subsubsec, findex
|
||||
# entry. This will generate empty @findex and @subsubsection entries if
|
||||
# the *proto* is on a line by itself; third pass removes them.
|
||||
/^\/\*proto\*/s/^\/\*proto\* *\(.*\)$/@findex \1\
|
||||
@subsubsection @code{\1}/
|
||||
#
|
||||
# /*proto-internal* is just like /*proto* from doc point of view.
|
||||
/^\/\*proto-internal\*/s/^\/\*proto-internal\* *\(.*\)$/@findex \1\
|
||||
@subsubsection @code{\1}/
|
||||
#
|
||||
# *i at beginning of line: rest of line is both a subsubsection heading
|
||||
# and an entry in function index.
|
||||
/^\*i/s/^\*i *\(.*\)$/@findex \1\
|
||||
@subsubsection @code{\1}/
|
||||
#
|
||||
# Two alternative docn block ends, '*/' and '*-*/' on lines by themselves;
|
||||
# replace by blank lines (for texinfo source readability).
|
||||
/^\*\/$/c\
|
||||
|
||||
/^\*-\*\/$/c\
|
||||
|
||||
# {* and *} are standins for comment markers (originally embedded in .c
|
||||
# comments)---turn into real comment markers:
|
||||
s/{\*/\/\*/
|
||||
s/\*}/\*\//
|
||||
#
|
||||
# '*+++' and '*---' span a block of text that includes both example lines
|
||||
# (marked by leading '$') and explanatory text (to be italicized).
|
||||
# Italicize lines lacking '$':
|
||||
/\*\+\+\+/,/\*---/s/^\([^$].*\)$/@i{\1}/
|
||||
#
|
||||
# We don't need *+++ and *--- markers any more; kill them (trailing marker
|
||||
# becomes blank line for readability)
|
||||
/\*\+\+\+/d
|
||||
/\*---/c\
|
||||
|
||||
# Any line beginning with '$' is made an example line; third pass later
|
||||
# coalesces adjacent example blocks. *DO NOT* introduce extra space after
|
||||
# @end example, so we can spot adjacent ones in third pass.
|
||||
/^\$/i\
|
||||
@example
|
||||
/^\$/a\
|
||||
@end example
|
||||
#
|
||||
# In any example line, turn '{' and '}' into '@{' and '@}'
|
||||
###/^\$/s/{/@{/g
|
||||
###/^\$/s/}/@}/g
|
||||
#
|
||||
# Now delete the '$' markers themselves:
|
||||
/^\$/s/\$//
|
||||
#
|
||||
# *+ and *- delimit large examples to be enclosed in cartouches.
|
||||
/^\*\+$/c\
|
||||
@lisp\
|
||||
@cartouche
|
||||
/^\*-$/c\
|
||||
@end cartouche\
|
||||
@end lisp\
|
||||
|
||||
# '*;' introduces an example which may have a single line or multiple lines;
|
||||
# it extends until the next semicolon (which is also printed).
|
||||
# One-line case: (do this first; else second line address for multi-line case
|
||||
# will include random text til we happen to end a line in a doc comment with
|
||||
# a semicolon)
|
||||
/^\*;.*;$/{
|
||||
s/^\*;/@example\
|
||||
/
|
||||
s/;$/;\
|
||||
@end example\
|
||||
/
|
||||
}
|
||||
# Multi-line case:
|
||||
/^\*;/,/.*;$/{
|
||||
s/^\*;/@example\
|
||||
/
|
||||
s/;$/;\
|
||||
@end example\
|
||||
/
|
||||
}
|
||||
|
|
@ -0,0 +1,63 @@
|
|||
# SED script for preprocessing embedded headers from source
|
||||
# (S. Chamberlain markup)
|
||||
# middle pass; most of the work is done here.
|
||||
#
|
||||
# First, get rid of /*proto* markers; they've done their job in the first pass.
|
||||
# (They remain comment-introducers)
|
||||
/^\/\*proto\*/s/^\/\*proto\*/\/*/
|
||||
/^\/\*proto-internal\*/s/^\/\*proto-internal\*/\/*/
|
||||
#
|
||||
# *-*/ is an alternative (older) comment-block end. Remap for uniformity:
|
||||
s/^\*-\*\//\*\//
|
||||
#
|
||||
# {* and *} are standins for comment markers (originally embedded in .c
|
||||
# comments)---turn into real comment markers:
|
||||
s/{\*/\/\*/
|
||||
s/\*}/\*\//
|
||||
#
|
||||
# '*+++' and '*---' span a block of text that includes both header lines
|
||||
# (marked by leading '$') and explanatory text (to be comments).
|
||||
# No need to start comment at "*+++", or end it at "*---", since we're
|
||||
# already in a *proto* comment block. Just delete.
|
||||
/\*\+\+\+/d
|
||||
/\*---/d
|
||||
#
|
||||
# Any line beginning with '$' is made a line of code in the header;
|
||||
# stuff in between is comments, so *precede* each '$' line with
|
||||
# END-comment, *follow* each '$' line with START-comment; third pass later
|
||||
# eliminates empty comment blocks.
|
||||
/^\$/i\
|
||||
*/
|
||||
/^\$/a\
|
||||
/*
|
||||
#
|
||||
# Now delete the '$' markers themselves:
|
||||
/^\$/s/\$//
|
||||
#
|
||||
# *+ and *- delimit larger blocks of code, treated the same as '$' lines
|
||||
/^\*\+$/c\
|
||||
*/
|
||||
/^\*-$/c\
|
||||
/*
|
||||
#
|
||||
# '*;' introduces code which may have a single line or multiple lines;
|
||||
# it extends until the next semicolon (which is also printed).
|
||||
#
|
||||
# One-line case: (do this first; else second line address for multi-line case
|
||||
# will include random text til we happen to end a line in a proto comment with
|
||||
# a semicolon)
|
||||
/^\*;.*;$/{
|
||||
s/^\*;/*\/\
|
||||
/
|
||||
s/;$/;\
|
||||
\/*\
|
||||
/
|
||||
}
|
||||
# Multi-line case:
|
||||
/^\*;/,/.*;$/{
|
||||
s/^\*;/*\/\
|
||||
/
|
||||
s/;$/;\
|
||||
\/*\
|
||||
/
|
||||
}
|
||||
|
|
@ -0,0 +1,12 @@
|
|||
# sed script for preprocessing BFD header files
|
||||
# <start comment> activity:
|
||||
/^\/\*$/{
|
||||
N
|
||||
# Delete empty comment blocks
|
||||
/^\/\*\n\*\/ *$/d
|
||||
# Transpose <start comment><blank line>
|
||||
s/^\/\*\n *$/\
|
||||
\/*/
|
||||
# merge <start comment> on line by itself with following line
|
||||
s/^\/\*\n\(.*\)/\/* \1/
|
||||
}
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
/---------------START FROM/,/---------------END FROM/d
|
||||
/\/\*:libbfd.c\*\//r libbfd.ip
|
||||
/\/\*:cache.c\*\//r cache.ip
|
||||
/\/\*:reloc.c\*\//r reloc.ip
|
||||
|
|
@ -0,0 +1 @@
|
|||
/\/\*:coffcode.h\*\//r coffcode.p
|
||||
|
|
@ -0,0 +1,18 @@
|
|||
#
|
||||
# The PROTO macro is a subterfuge to be compatible with both ANSI and K&R
|
||||
# declaration syntax. It's not widely known, so for the docn just map the
|
||||
# thing to ANSI declaration syntax.
|
||||
#
|
||||
# First, join up defns broken across multiple lines in source---but leave
|
||||
# any linebreaks, to prettify our examples
|
||||
:pbegn
|
||||
/PROTO(.*, *$/N
|
||||
s/\n/?/
|
||||
t pbegn
|
||||
s/?/\
|
||||
/g
|
||||
# Now actually do the PROTO interpretation.
|
||||
# A PROTO invocation looks like
|
||||
# PROTO( resulttype, function, (arglist));
|
||||
s/[ ]*PROTO(\(.*\),[\n ]*\(.*\),[\n ]*\((.*)\));/\1 \2\3;/
|
||||
|
||||
Loading…
Reference in New Issue