home *** CD-ROM | disk | FTP | other *** search
/ CD Actual 13 / CDA13.ISO / DOC / HOWTO / OTHER_FO / SGML / ELF_HOWT.GZ / ELF-HOWTO.sgml
Encoding:
SGML Document  |  1996-08-02  |  54.2 KB  |  1,352 lines

  1.              <!-- Warning to the author: -->
  2. <!-- Automatically generated by /home/dan/doc/howto/makeindex.pl: EDIT THE SOURCE INSTEAD -->
  3. <!doctype linuxdoc system>
  4. <!--     $Id: ELF-HOWTO.sgmlp,v 1.29 1996/07/14 19:09:17 dan Exp $     -->
  5. <article>
  6.  
  7. <title>The Linux ELF HOWTO
  8. <author>Daniel Barlow <tt><daniel.barlow@linux.org></tt>
  9. <date>v1.29, 14 July 1996
  10.  
  11. <abstract>
  12. This document describes how to migrate your Linux system to compile
  13. and run programs in the ELF binary format.  It falls into three
  14. conceptual parts: (1) What ELF is, and why you should upgrade,
  15. (2) How to upgrade to ELF-capability, and (3) what you can do then.
  16.  
  17. After a fairly long fallow period in which I have been pretending to
  18. do academic work, it has recently been overhauled to give current
  19. information for Linux 2.0. 
  20.  
  21. </abstract>
  22.  
  23. <sect>What is ELF?  An introduction
  24.  
  25. <p>
  26.  
  27. <p> ELF (Executable and Linking Format) is a binary format originally
  28. developed by USL (UNIX System Laboratories) and currently used in
  29. Solaris and System V Release 4.  Because of its increased flexibility
  30. over the older a.out format that Linux previously used, the GCC and C
  31. library developers decided last year to move to using ELF as the Linux
  32. standard binary format also.
  33.  
  34. This `increased flexibility' manifests as essentially two benefits to
  35. the average applications progammer:
  36.  
  37. <itemize>
  38.  
  39. <item> It is much simpler to make shared libraries with ELF.
  40. Typically, just compile all the object files with <tt>-fPIC</tt>, then
  41. link with a command like
  42.  
  43. <tscreen><verb> gcc -shared -Wl,-soname,libfoo.so.y -o libfoo.so.y.x *.o 
  44. </verb></tscreen>
  45.  
  46. If that looks complex, you obviously haven't ever read up on the
  47. equivalent procedure for a.out shared libraries, which involves
  48. compiling the library twice, reserving space for all the data you
  49. think that the library is likely to require in future, and registering
  50. that address space with a third party (it's described in a document
  51. over 20 pages long --- look at
  52. <url url=
  53. "ftp://tsx-11.mit.edu/pub/linux/packages/GCC/src/tools-2.17.tar.gz">
  54. for details).
  55.  
  56. <item>It makes dynamic loading (ie programs which can load modules at
  57. runtime) much simpler.  This is used by Perl 5, Python, and Java,
  58. among other things (it's a kicker for many kinds of interpreters).
  59. Other suggestions for dynamic loading have included super-fast MUDs,
  60. where extra code could be compiled and linked into the running
  61. executable without having to stop and restart the program.
  62.  
  63. </itemize>
  64.  
  65. <p>Against this it must be weighed that ELF is possibly a bit slower.
  66. The figures that get bandied around are between 1% and 5%, though all
  67. the actual tests that have been conducted so far indicate that the
  68. difference is small enough to get lost in the noise of other events
  69. happening at the same time.  If you have TeX or a Postscript
  70. viewer/printer, you can read <tt/speed.comp-1.0.tar.gz/, which is
  71. available from SunSite somewhere.
  72.  
  73. The slowdown comes from the fact that ELF library code must be
  74. position independent (this is what the <tt>-fPIC</tt> above stands
  75. for) and so a register must be devoted to holding offsets.  That's one
  76. less for holding variables in, and the 80x86 has a paucity of
  77. general-purpose registers anyway.  Note that the speed difference only
  78. applies to code that is part of shared libraries.  For applications or
  79. kernels there is no speed difference between a.out and ELF.
  80.  
  81. <sect1> What ELF isn't
  82.  
  83. <p> There are a number of common misconceptions about what ELF will do
  84. for your system:
  85.  
  86. <descrip>
  87. <tag/It's not a way to run SVR4 or Solaris programs/
  88.  
  89. Although it's the same binary `container' as SVR4 systems use, that
  90. doesn't mean that SVR4 programs suddenly become runnable on Linux.
  91. It's analogous to a disk format --- you can keep Linux programs on
  92. MSDOS or Minix-format disks, and vice versa, but that doesn't mean
  93. that these systems become able to run each others' programs.  
  94.  
  95. It may be possible to run an application for another x86 Unix under
  96. Linux (it depends on the application), but following the instructions
  97. in this HOWTO will <em/not/ have that effect.  Start by looking at the
  98. iBCS kernel module (somewhere on <tt/tsx-11.mit.edu/) and see if it
  99. fits your needs.
  100.  
  101. <tag/It's not intrinsically smaller or faster/
  102.  
  103. You may well end up with smaller binaries anyway, though, as you can
  104. more easily create shared libraries of common code between many
  105. programs.  In general, if you use the same compiler options and your
  106. binaries come out smaller than they did with a.out, it's more likely
  107. to be fluke or a different compiler version.  As for `faster', I'd be
  108. surprised.  Speed increases could turn up if your binaries are
  109. smaller, due to less swapping or larger functional areas fitting in
  110. cache.
  111.  
  112. <tag/It doesn't require that you replace every binary on your system/
  113.  
  114. At the end of this procedure you have a system capable of compiling
  115. and running both ELF and a.out programs.  New programs will by default
  116. be compiled in ELF, though this can be overridden with a command-line
  117. switch.  There is admittedly a memory penalty for running a mixed
  118. ELF/a.out system --- if you have both breeds of program running at
  119. once you also have two copies of the C library in core, and so on.
  120. I've had reports that the speed difference from this is undetectable
  121. in normal use on a 6Mb system though (I certainly haven't noticed much in
  122. 8Mb), so it's hardly pressing.  You lose far more memory every day by
  123. running bloated programs like Emacs and static Mosaic/Netscape
  124. binaries :-)
  125.  
  126. <tag/It's nothing to do with Tolkien./
  127.  
  128. Or at least, not in this context.  
  129.  
  130. </descrip>
  131.  
  132. <sect1> Why you should convert to ELF
  133.  
  134. <p> There are essentially two reasons to upgrade your system to
  135. compile and run ELF programs: the first is the increased flexibility
  136. in programming referred to above, and the second is that, due to the
  137. first, everyone else will (or has already).  Current releases of the C
  138. library and GCC are compiled only for ELF, and other developers are
  139. moving ELFwards too.
  140.  
  141. Many people are concerned about stability (justifiably so, even if
  142. it's not so much fun).  ELF on Linux has existed since August 1994 and
  143. has been publically available since May or June 1995; the teething
  144. troubles are probably out of the way by now.  You should allow for the
  145. possibility of breaking things --- as you would with any major upgrade
  146. --- but the technology that you're upgrading to is no longer bleeding
  147. edge.  For a system on which any development is done, or on which you
  148. want to run other people's precompiled binaries, ELF is pretty much a
  149. necessity these days.  Plan to switch to it when you upgrade to
  150. version 2.0 of the kernel.
  151.  
  152. <sect1> How to convert to ELF
  153.  
  154. <p> When this HOWTO was first written, there was only one way, and it
  155. was the way described here.  These days there are high-quality
  156. upgradable distributions available --- unless you have invested
  157. significant time in setting up your machine exactly how you like it,
  158. you might find that a backup of all your own data and a reinstall from
  159. a recent Red Hat or Debian release is more convenient than messing
  160. about with the assorted libraries and compilers described here.
  161.  
  162. I must stress this.  The installation described here is a fairly small
  163. job in itself (it can be completed in well under an hour, excepting
  164. the time taken to download the new software), but there are a
  165. multitude of errors that you can make which will probably leave you
  166. with an unbootable system.  If you are not comfortable with upgrading
  167. shared libraries, if the commands <tt>ldconfig</tt> and <tt> ldd</tt>
  168. mean nothing to you, or if you're unhappy about building packages from
  169. source code, you should consider the `easy option'.  Even if this
  170. description isn't you, think about it anyway --- if you want a `fully
  171. ELF' system, <em>somebody</em> is going to have to recompile all the
  172. binaries on it.
  173.  
  174. Still with us?
  175.  
  176. <sect> Installation
  177.  
  178. <sect1> Background
  179.  
  180. <p> The aim of this conversion is to leave you with a system which can
  181. build and run both a.out and ELF programs, with each type of program
  182. being able to find its appropriate breed of shared libraries.  This
  183. obviously requires a bit more intelligence in the library search
  184. routines than the simple `look in <tt>/lib</tt>, <tt>/usr/lib</tt> and
  185. anywhere else that the program was compiled to search' strategy that
  186. some other systems can get away with.
  187.  
  188. This intelligence is centralised in a <em/dynamic loader/, which
  189. exists in only one --- or two --- places on the system.  For a.out
  190. programs, it's called <tt>/lib/ld.so</tt>, and for ELF programs it's
  191. <tt>/lib/ld-linux.so.1</tt>.  The compiler and linker do not encode
  192. absolute library pathnames into the programs they output; instead they
  193. put the library name and the absolute path to the appropriate dynamic
  194. loader in, and leave that to match the library name to the appropriate
  195. place at runtime.  This has one very important effect --- it means
  196. that the libraries that a program uses can be moved to other
  197. directories <em> without recompiling the program</em>, provided that
  198. <tt/ld.so/ (<tt/ld-linux.so.1/; whatever) is told to search the new
  199. directory.  This is essential functionality for the directory swapping
  200. operation that follows.
  201.  
  202. The corollary of the above, of course, is that any attempt to delete
  203. or move <tt>ld.so</tt> or <tt>ld-linux.so.1</tt> may cause <em>every
  204. dynamically linked program on the system to stop working</em>.  This
  205. is generally regarded as a Bad Thing.
  206.  
  207. The basic plan, then, is that ELF development things (compilers,
  208. include files and libraries) go into <tt>/usr/{bin,lib,include}</tt>
  209. where your a.out ones currently are, and the a.out things will be
  210. moved into <tt>/usr/i486-linuxaout/{bin, lib, include}</tt>.
  211. <tt>/etc/ld.so.conf</tt> lists all the places on the system where
  212. libraries are expected to be found, and <tt/ldconfig/ is intelligent
  213. enough to distinguish between ELF and a.out variants.  
  214.  
  215. There are a couple of exceptions to the library placement:
  216. <itemize>
  217.  
  218. <item> Some old programs were built without the use of <tt/ld.so/.
  219. These would all cease working if their libraries were moved from under
  220. them.  Thus, <tt/libc.so*/ and <tt/libm.so*/ must stay where they are
  221. in <tt>/lib</tt>, and the ELF versions have had their major numbers
  222. upgraded so that they do not overwrite the a.out ones.  Old X
  223. libraries (prior to version 6) are best left where they are also,
  224. although newer ones (<tt/libX*so.6/) must be moved.  Moving the old
  225. ones will apparently break xview programs, and not moving the new ones 
  226. will cause them to be overwritten when you install ELF X libraries.
  227.  
  228. If you have non-ld.so programs that require libraries other than the
  229. above (if you know which programs they are, you can run ldd on them to
  230. find out which libraries they need <em/before/ breaking them) you have
  231. essentially two options.  One, you can extract the ELF library tar
  232. files into a temporary directory, check whether your precious library
  233. would be overwritten, and if so, move the ELF version of the library
  234. into, say, <tt>/usr/i486-linux/lib</tt> instead of <tt>/lib</tt>.
  235. Make sure your <tt/ld.so.conf/ has <tt>/usr/i486-linux/lib</tt> in it,
  236. then run <tt/ldconfig/ and think no more on't.  Two, you can recompile
  237. or acquire a newer copy of the offending program.  This might not be a
  238. bad idea, if possible.
  239.  
  240. <item> If you have <tt>/usr</tt> and <tt>/</tt> on different
  241. partitions, any libraries that you move from <tt>/lib</tt> must end up
  242. somewhere else on the root disk, not on <tt>/usr</tt>.  I used
  243. <tt>/lib-aout</tt> in the instructions that follow.
  244.  
  245. </itemize>
  246.  
  247. <sect1> Before you start --- Notes and Caveats
  248.  
  249. <p>
  250. <itemize>
  251.  
  252. <item> You will need to be running a post-1.1.52 <bf>kernel with ELF
  253. binary format support</bf>.  1.2.13 works.  2.0.0 (the most recent at
  254. the time of writing) also works, as do most of the 1.3 series, though
  255. the point of running old `experimental' kernels is anyway questionable
  256. now that 2.0 is here.
  257.  
  258. <item> You are recommended to prepare or acquire a linux boot/root
  259. disk, such as a Slackware rescue disk.  You probably won't need it,
  260. but if you do and you don't have one, you'll kick yourself.  In a
  261. similar `prevention is better than cure' vein, statically linked
  262. copies of <tt/mv/, <tt/ln/, and maybe other file manipulation commands
  263. (though in fact I think you can do everything else you actually
  264. <em>need</em> to with shell builtins) may help you out of any awkward
  265. situations you could end up in.
  266.  
  267. <item> If you were following the early ELF development, or you
  268. installed certain versions of Slackware (none of the current ones,
  269. admittedly) you may have ELF libraries in <tt>/lib/elf</tt> (usually
  270. <tt>libc.so.4</tt> and co).  Applications that you built using these
  271. should be rebuilt, then the directory removed.  There is no need for a
  272. <tt>/lib/elf</tt> directory!
  273.  
  274. <item> Most Linux installations these days have converged on the
  275. `FSSTND' standard file system, but doubtless there are still installed
  276. systems that haven't.  If you see references to
  277. <tt>/sbin/</tt><em>something</em> and you don't have a <tt>/sbin</tt>
  278. directory, you'll probably find the program referred to in
  279. <tt>/bin</tt> or <tt>/etc/</tt>.  It is especially important to check
  280. this when you install new programs; if you have <tt>/etc</tt> nearer
  281. the front of the search path than <tt>/sbin</tt> you'll get odd
  282. failures due to running the old versions when you weren't expecting
  283. to.
  284.  
  285. <item> It's a good idea to pick a time when nobody else is using the
  286. computer, or to take it single-user.  It might be a good idea to
  287. reboot it off a floppy so that a mistake doesn't leave you stuck, but
  288. personally I like to leave a <em>small</em> element of fun ...
  289.  
  290. </itemize>
  291.  
  292. <sect1> Ingredients
  293.  
  294. <p> Anything in the following list that I describe as being ``on
  295. <tt/tsx-11/'' can be found in <url
  296. url="ftp://tsx-11.mit.edu/pub/linux/packages/GCC/">, <url
  297. url="ftp://sunsite.unc.edu/pub/Linux/GCC/">, and at many mirrors.
  298. Please take the time to look up your nearest mirror site and use that
  299. instead of the master sites where possible.  It's faster for both you
  300. and everyone else.
  301.  
  302. These packages (either the listed version or a later one) are
  303. required.  Also download and read through the release notes for each
  304. of them: these are the files named <tt/release./<em/packagename/.
  305. This applies especially if you get newer versions than are listed
  306. here, as procedures may have changed.
  307.  
  308. Even if you habitually compile things from source, I'd advise you to
  309. go for the binary versions where I've indicated, unless you
  310. <em>really</em> have no use for your hair.  Most of them are not set
  311. up for `crosscompiling' on an a.out-based system, and you are probably
  312. lining yourself up for major grief if you try.
  313.  
  314. <sect2> Absolute essentials
  315.  
  316. <p>
  317. <itemize>
  318.  
  319. <item> <tt/ld.so-1.7.14.tar.gz/ --- the new dynamic linker.  Contains
  320. both source and binaries.  Note that forthcoming versions of this will
  321. require kernel ELF support even for a.out binaries; if you get 1.8.1
  322. or later instead of the version listed, make sure that the kernel
  323. you're running was compiled with ELF support <em/before/ you install
  324. this.
  325.  
  326. <item> <tt/libc-5.3.12.bin.tar.gz/ --- the ELF shared images for the C
  327. and maths libraries, plus the corresponding static libraries and the
  328. include files needed to compile programs with them.  Source is also
  329. available if you like it, but it takes ages to compile, and probably
  330. won't at all unless you already have an ELF system.
  331.  
  332. <item> <tt/gcc-2.7.2.bin.tar.gz/ --- the ELF C compiler package, which
  333. also includes an a.out C compiler which understands the new directory
  334. layout.  If you want to build gcc yourself (which you'll probably find
  335. is simpler when you're already running ELF), you're recommended to
  336. apply <tt/gcc-2.7.2-linux.diff.gz/ to the GNU sources first.
  337.  
  338. <item> <tt/binutils-2.6.0.12.bin.tar.gz/ --- the GNU binary utilities
  339. patched for Linux.  These are programs such as <tt/gas/, <tt/ld/,
  340. <tt/strings/ and so on, most of which are required to make the C
  341. compiler go.  Note that the vanilla GNU binutils (e.g. from
  342. <tt/prep.ai.mit.edu/) are not an acceptable substitute; if you really
  343. want to compile this yourself you'll need to use the patched-for-Linux 
  344. <tt/binutils-2.6.0.12.tar.gz/ package instead of the GNU one.
  345.  
  346. <item> <tt/ncurses-1.9.9e.tar.gz/ --- this is an SVR4-compatible
  347. curses library, which is henceforward deemed to be the `standard
  348. curses library' for Linux.  The source is available from GNU sites
  349. such as <url url="ftp://prep.ai.mit.edu/gnu/"> and also from <url
  350. url="ftp://ftp.netcom.com/pub/zm/zmbenhal">, and there is a binary
  351. package on <tt/tsx-11/.  By the time you get to install this you will
  352. have a fully functional ELF development system, so I recommend the
  353. source package if you have any kind of compilation horsepower.  That
  354. may just be me, though.
  355.  
  356. <item> <tt/gdbm-1.7.3.tar.gz/ is a set of database routines that use
  357. extensible hashing and work similarly to the standard UNIX dbm and
  358. ndbm routines.  The source is available from GNU sites such as <url
  359. url="ftp://prep.ai.mit.edu/gnu/">; you also need a patch <url
  360. url="ftp://ftp.uk.linux.org/pub/Linux/libc/non-core/gdbm.patch"> to
  361. make shared libraries out of it.  That patch also fixes a couple of
  362. other things (a one-character typo in the Makefile and a
  363. predisposition to use the wrong kind of file locking).
  364.  
  365. </itemize>
  366.  
  367. <sect2> Others
  368.  
  369. <p> These are other libraries and files which aren't strictly
  370. essential, but that you might want to get anyway.  This list contains
  371. only packages that need to be upgraded to work in an ELF-useful
  372. fashion.  Later in this document is another list of programs which
  373. will continue to work but which you'll have to tweak/upgrade if you
  374. want to recompile them in ELF.  If your net access involves
  375. high-latency links (like, say, a five-minute walk with a box of floppy
  376. disks), skip forwards and check that one too before you set out :-)
  377.  
  378. <itemize>
  379.  
  380. <item> The <bf>a.out compatibility</bf> library package,
  381. <tt>libc.so-4.7.6</tt>.  This is listed as `optional' because your
  382. existing a.out libraries of whatever vintage will continue to work
  383. fine with your existing binaries.  You might find that you need this
  384. if you plan to continue developing in a.out for whatever reason.
  385.  
  386. <item> <bf>BSD curses</bf>.  If you find binaries which require
  387. <tt/libcurses.so.1/, this is the old BSD curses library.  They're
  388. probably quite rare, which is fortunate as I can't presently find a
  389. (source code) copy of the library.  It's probably best to recompile
  390. programs like this to use ncurses; if this is not an option, there is
  391. a binary <tt/libcurses.so/ in the <tt/libc-5.0.9.bin.tar.gz/ on
  392. <tt/tsx-11/ mirrors.
  393.  
  394. <item> <bf>Berkeley db</bf>: the new 4.4BSD <tt/libdb/ database
  395. routines.  The source can be had from <url
  396. url="ftp://ftp.cs.berkeley.edu/ucb/4bsd/db.1.85.tar.gz/">, and the patch
  397. for Linux shared libraries is <url
  398. url="ftp://ftp.uk.linux.org/pub/Linux/libc/non-core/db.patch">
  399.  
  400. <item> <bf>C++ stuff.</bf> The <tt>gcc</tt> package comes with
  401. <tt/g++/, but you'll also need <tt/libg++-2.7.1.4.bin.tar.gz/ to
  402. compile any useful C++ software.  I don't use C++ myself, but I
  403. understand that it is nontrivial to build this from source, hence the
  404. binary recommendation.
  405.  
  406. <item> <bf>GNU-compatible termcap</bf>.  The conversion to ncurses din't
  407. happen simultaneously with the move to ELF --- you might find that you
  408. want to run other people's programs that were built using this
  409. library, and for some applications you might wish to continue using
  410. it.  <tt>gdb</tt> is a legitimate example.  If you intend to debug
  411. shared libraries and you think that gdb is getting confused about the
  412. ones that it's linked with itself, you probably want a statically
  413. linked copy of it; in this case, you'll find that a real termcap is a
  414. lot smaller than the termcap-compatible routines in ncurses.
  415.  
  416. <tt/termcap-2.0.8.tar.gz/ is available from <tt/tsx-11/.  This is
  417. <em/not/ GNU Termcap, but it is completely compatible (the differences
  418. are in the error checking, apparently).  This is a source code package.
  419.  
  420. <item> <bf>MAKEDEV</bf>.  In some incarnations, this utility removes
  421. existing entries for devices before recreating them.  This is Bad News
  422. if it removes <tt>/dev/zero</tt>, which causes some versions of
  423. <tt/ld-linux.so.1/ to break.  Find a new version at
  424. <url url="ftp://sunsite.unc.edu/pub/Linux/system/Admin/MAKEDEV-C-1.5.tar.gz">
  425. or
  426. <url url="ftp://sunsite.unc.edu/pub/Linux/system/Admin/MAKEDEV-2.2.tar.gz">.
  427.  
  428. <item> <tt>modules-2.0.0</tt>.  If you use modules, the upgrade to
  429. binutils which you're shortly about to perform will break all versions
  430. of the modules utilities older than 1.3.69.  New modules utilities can
  431. be had from <url url="http://www.pi.se/blox/">.
  432.  
  433. <item> The <bf>X window system</bf> includes a lot of shared libraries.
  434. As your new programs will be ELF, and ELF programs cannot use a.out
  435. libraries, you'll need a new X installation if you want to do any X
  436. development.  XFree86 3.1.2 comes in both a.out and ELF formats.
  437. <tt/ftp/ to <tt/ftp.xfree86.org/, read the `too many users' message
  438. that you are almost guaranteed to get, and pick the closest mirror
  439. site network-wise to you.  Once you have the contents of the
  440. <tt/common/ and <tt/elf/ directories, you must edit
  441. <tt>/usr/X11R6/lib/X11/config/linux.cf</tt> to change the lines saying
  442.  
  443. <tscreen><verb>
  444. #define LinuxElfDefault         NO
  445. #define UseElfFormat            NO
  446. </verb></tscreen>
  447.  
  448. to say <tt/YES/ instead.  Otherwise an xpm build will attempt to do
  449. odd stuff with <tt/jumpas/ and its associated relics of the past.
  450. Note that XFree86 binaries currently require an ELF shared termcap
  451. library (<tt/libtermcap.so.2/) to be installed.
  452.  
  453. If you use Motif, you may also need to contact your vendor, to
  454. investigate whether they will supply ELF Motif libraries.  I don't use
  455. it; I can't help here.
  456.  
  457. <item> If you're upgrading to Linux 2.0 at the same time as going ELF,
  458. don't forget also to check the <tt>Documentation/Changes</tt> file
  459. that comes in the kernel source, to find out what else you'll need.
  460.  
  461. </itemize>
  462.  
  463. <sect1> Rearranging your filesystem
  464.  
  465. <p> Sooo...  Note that in all that follows, when I say `remove' I
  466. naturally mean `backup then remove' :-).  Take a deep breath ...
  467.  
  468. <enum>
  469.  
  470. <p> <bf/ The essentials --- binary installation/
  471.  
  472. <item> Make the new directories that you will move a.out things to
  473. <tscreen><verb>
  474. mkdir -p /usr/i486-linuxaout/bin
  475. mkdir -p /usr/i486-linuxaout/include
  476. mkdir -p /usr/i486-linuxaout/lib
  477. mkdir /lib-aout
  478. </verb></tscreen>
  479.  
  480. <item> Untar the dynamic linker package <tt>ld.so-1.7.14</tt> in the
  481. directory you usually put source code, then read through the
  482. <tt>ld.so-1.7.14/instldso.sh</tt> script just unpacked.  If you
  483. have a really standard system, run it by doing <tt>sh instldso.sh</tt>,
  484. but if you have anything at all unusual then do the install by hand
  485. instead.  `Anything at all unusual' includes 
  486. <itemize>
  487.  
  488. <item> using zsh as a shell (some versions of zsh define
  489. <tt/$VERSION/, which seems to confuse <tt/instldso.sh/) 
  490.  
  491. <item> having symlinks from <tt>/lib/elf</tt> to <tt>/lib</tt> (which
  492. you shouldn't need, but that's scant consolation when you're looking
  493. for the rescue disk)
  494.  
  495. </itemize>
  496.  
  497. <item> Edit <tt>/etc/ld.so.conf</tt> to add the new directory
  498. <tt>/usr/i486-linuxaout/lib</tt> (and <tt>/lib-aout</tt> if you're
  499. going to need one).  Then rerun <tt>/sbin/ldconfig -v</tt> to check
  500. that it is picking up the new directories.
  501.  
  502. <item> Move all the a.out libraries in <tt>/usr/lib</tt> and
  503. <tt>/usr/*/lib</tt> to <tt>/usr/i486-linuxaout/lib</tt>.  Note, I said
  504. `libraries' not `everything'.  That's files matching the specification
  505. <tt/lib*.so*/ , <tt/lib*.sa*/, or <tt/lib*.a/.  Don't start moving
  506. <tt>/usr/lib/gcc-lib</tt> or anything silly like that around.
  507.  
  508. <item> Now look at <tt>/lib</tt>.  Leave intact <tt/libc.so*/,
  509. <tt/libm.so*/, and <tt/libdl.so*/.  If you have symlinks to X
  510. libraries (<tt/libX*.so.3*/) leave them there too --- XView and some other
  511. packages may require them.  Leave <tt/ld.so*/, <tt/ld-linux.so*/ and
  512. any other files starting with <tt/ld/.  As for the remaining libraries
  513. (if there are any others): if you have <tt>/usr</tt> on the root
  514. partition, put them in <tt>/usr/i486-linuxaout/lib</tt>.  If you have
  515. <tt>/usr</tt> mounted separately, put them in <tt>/lib-aout</tt>.
  516. Now run <tt/ldconfig -v/
  517.  
  518. <item> Remove the directory <tt>/usr/lib/ldscripts</tt> if it's there,
  519. in preparation for installing the binutils (which will recreate it)
  520.  
  521. <item> Remove any copies of <tt>ld</tt> and <tt>as</tt>
  522. (<em>except</em> for <tt>ld86</tt> and <tt>as86</tt>) that
  523. you can find in <tt>/usr/bin</tt>. 
  524.  
  525. <item> You need to clean up your <tt>/usr/include</tt> hierarchy.  
  526. On an average system, some of the files in here are `core'
  527. functionality and come with libc, while others are from other packages
  528. that you or your distribution builder have installed.  Given this
  529. mess, I suggest you remake it from scratch; rename it to
  530. <tt>/usr/include.old</tt>, then unpack <tt>libc-5.2.18.bin.tar.gz
  531. </tt> by untarring it from the root directory.
  532.  
  533. <item> Install the binutils package.  <tt>tar -xvzf
  534. binutils-2.6.0.12.bin.tar.gz -C / </tt> is one perfectly good way to
  535. do this.
  536.  
  537. <item> The gcc package expects to be untarred from root.  It installs
  538. some files in <tt>/usr/bin</tt> and lots more in
  539. <tt>/usr/lib/gcc-lib/i486-linux/2.7.2</tt> and
  540. <tt>/usr/lib/gcc-lib/i486-linuxaout/2.7.2</tt>.  Use 
  541.  
  542. <tscreen><verb>
  543. $ tar ztf gcc-2.7.2.bin.tar.gz
  544. </verb></tscreen>
  545.  
  546. to see what's in it, backup anything that it overwrites that you feel
  547. you may want to keep (for example, if you have Gnu ADA installed you
  548. will probably want to keep <tt>/usr/bin/gcc</tt>), then just do
  549.  
  550. <tscreen><verb>
  551. # tar -zxf gcc-2.7.2.bin.tar.gz -C /
  552. </verb></tscreen>
  553.  
  554. At this point, you should be able to run <tt>gcc -v</tt> and compile
  555. test programs.  Try
  556.  
  557. <tscreen><verb>
  558. $ gcc -v
  559. Reading specs from /usr/lib/gcc-lib/i486-linux/2.7.2/specs
  560. gcc version 2.7.2
  561. $ gcc -v -b i486-linuxaout
  562. Reading specs from /usr/lib/gcc-lib/i486-linuxaout/2.7.2/specs
  563. gcc version 2.7.2
  564. $ ld -V
  565. ld version 2.6 (with BFD 2.6.0.2)
  566.   Supported emulations:
  567.    elf_i386 
  568.    i386linux 
  569.    i386coff 
  570. </verb></tscreen>
  571.  
  572. followed of course by the traditional ``Hello, world'' program.  Try
  573. it with <tt/gcc/ and with <tt/gcc -b i486-linuxaout/ to check that
  574. both the a.out and ELF compilers are set up correctly.
  575.  
  576. Finished?  Not quite.  You still have all the `non-core' libraries to
  577. install, and a fair amount of mucking about with symlinks.  Onwards...
  578.  
  579. <p> <bf/ Symlinks /
  580.  
  581. <item> Some programs (notably various X programs) use
  582. <tt>/lib/cpp</tt>, which under Linux is generally a link to
  583. <tt>/usr/lib/gcc-lib/i486-linux/</tt><em/version/<tt>/cpp</tt>.  As
  584. the preceding step probably wiped out whatever version of <tt/cpp/ it
  585. was pointing to, you'll need to recreate the link:
  586.  
  587. <tscreen><verb>
  588. # cd /lib
  589. # ln -s /usr/lib/gcc-lib/i486-linux/2.7.2/cpp .
  590. </verb></tscreen>
  591.  
  592. <item> When you moved <tt>/usr/include</tt> to <tt>/usr/include.old</tt>, you
  593. lost the symlinks into the kernel sources.  Run
  594.  
  595. <tscreen><verb>
  596. # cd /usr/include
  597. # ln -s ../src/linux/include/linux .
  598. # ln -s ../src/linux/include/asm .
  599. </verb></tscreen>
  600.  
  601. (assuming you have kernel source in <tt>/usr/src/linux</tt>; if not,
  602. season to taste)
  603.  
  604. <item> The FSSTND people have once again justified their keep by
  605. moving the <tt/utmp/ and <tt/wtmp/ files from <tt>/var/adm</tt> to
  606. <tt>/var/run</tt> and <tt>/var/log</tt> respectively.  You'll need to
  607. add some links dependent on where they currently live, and you may
  608. need to make the <tt>/var/log</tt> and <tt>/var/adm</tt> directories
  609. too.  I reproduce below the <tt/ls -l/ output of appropriate bits on
  610. my system:
  611.  
  612. <tscreen><verb>
  613. $ ls -ld /var/adm /var/log /var/run /var/log/*tmp /var/run/*tmp
  614. lrwxrwxrwx   1 root     root            3 May 24 05:53 /var/adm -> log/
  615. drwxr-xr-x   9 root     root         1024 Aug 13 23:17 /var/log/
  616. lrwxrwxrwx   1 root     root           11 Aug 13 23:17 /var/log/utmp -> ../run/utmp
  617. -rw-r--r--   1 root     root       451472 Aug 13 23:00 /var/log/wtmp
  618. drwxr-xr-x   2 root     root         1024 Aug 13 23:17 /var/run/
  619. -rw-r--r--   1 root     root          448 Aug 13 23:00 /var/run/utmp
  620. </verb></tscreen>
  621.  
  622. Check the FSSTND (from LDP archives such as <url
  623. url="ftp://sunsite.unc.edu/pub/Linux/docs/fsstnd/">) for the full
  624. story.
  625.  
  626. <p> <bf/Rejoice! /
  627.  
  628. By this time you should have a (more or less) fully functioning ELF
  629. development system.  Stand back and celebrate quietly for a few minutes.
  630.  
  631. <p> <bf/Essential source code packages /
  632.  
  633. <item> <bf>ncurses installation</bf> is a fairly long job, though most
  634. of of the time can be spent reading Usenet while it builds.  After
  635. unpacking the tar file, read the <tt/INSTALL/ file pretending that you
  636. are `a Linux [...] distribution integrator or packager'; that is, you
  637. probably want to be configuring it with a command like
  638.  
  639. <tscreen><verb>
  640. $ ./configure --with-normal --with-shared --disable-termcap --enable-overwrite --prefix=/usr
  641. </verb></tscreen>
  642.  
  643. Take heed also of the comments about the default terminal type; in 1.3
  644. and 2.0 kernels this is set to <tt/linux/ at boot time, but you may
  645. find that you need to edit <tt>/etc/inittab</tt> to avoid having it set
  646. back to <tt/console/ by <tt/getty/.
  647.  
  648. If you do not have <tt>/usr/lib/terminfo</tt> on the root disk you will
  649. have to fiddle with the `fallback' support in ncurses.  This is
  650. documented in the <tt/INSTALL/ file mentioned above, and is simple but
  651. tedious (due to the necessity of building the library twice).  If
  652. you're happy with having <tt/linux/ and <tt/vt100/ as fallbacks, there
  653. is a ready-prepared <tt/fallback.c/ at <url
  654. url="ftp://ftp.uk.linux.org/pub/Linux/libc/non-core/fallback.c"> which
  655. you can copy over the existing one.
  656.  
  657. After you have installed ncurses, you'll have to get messy in
  658. <tt>/usr/lib</tt> --- it does some non-optimal things that are simplest to
  659. clear up by hand.  Note the weird discrepancy between the version
  660. numbers; this is ugly but not actually detrimental to human health.
  661.  
  662. <enum>
  663.  
  664. <item> <tt>/usr/lib/libncurses.so.1.9.9e</tt> should be moved to <tt>/lib</tt>
  665. so that curses programs which run in single-user mode will continue to
  666. do so.  If you have <tt>/usr/lib</tt> on the root partition, this is
  667. unnecessary but will do no harm.
  668.  
  669. <item> In <tt>/lib</tt>, make a link to <tt/libncurses.so.1.9.9e/ called
  670. <tt/libncurses.so.3.0/.
  671.  
  672. <item> You also need links <tt>/usr/lib/libncurses.so</tt>,
  673. <tt>/usr/lib/libcurses.so</tt> and <tt>/usr/lib/libtermcap.so</tt> which
  674. should all point to <tt>/lib/libncurses.so.3.0</tt>. 
  675. </enum>
  676.  
  677. In brief for the hard of thinking, that little lot was
  678.  
  679. <tscreen><verb>
  680. # cd /lib
  681. # mv /usr/lib/libncurses.so.1.9.9e .
  682. # ln -s libncurses.so.1.9.9e libncurses.so.3.0 
  683. # cd /usr/lib
  684. # ln -s /lib/libncurses.so.3.0 libncurses.so
  685. # ln -s /lib/libncurses.so.3.0 libcurses.so
  686. # ln -s /lib/libncurses.so.3.0 libtermcap.so
  687. </verb></tscreen>
  688.  
  689. <item> <bf/gdbm/ installation.  Unpack the source code in a source
  690. code directory, apply <tt/gdbm.patch/, and look over the <tt/README/
  691. and <tt/INSTALL/ files.  
  692.  
  693. The build process should go something like:
  694.  
  695. <tscreen><verb>
  696. $ tar zxf gdbm-1.7.3.tar.gz
  697. $ patch -p0 < gdbm.patch
  698. $ cd gdbm-1.7.3
  699. $ ./configure --prefix=/usr
  700. $ make 
  701. $ make progs
  702. $ su
  703. # make install
  704. # make install-compat
  705. # cd /usr/lib
  706. # ln -s libgdbm.so.1 libgdbm.so
  707. # ln -s libgdbm.so.1 libgdbm.so.2
  708. # ldconfig
  709. </verb></tscreen>
  710.  
  711. The last step is for backward-compatibility; some current
  712. distributions use <tt/libgdbm.so.2/ which is exactly the same code as
  713. <tt/libgdbm.so.1/, but misnumbered for historical reasons.
  714.  
  715. <p> <bf/Optional source code packages/.  In general, you can just
  716. install these according to their instructions, so I won't repeat them.
  717. There are two exceptions, though:
  718.  
  719. <item> If you want the <bf>GNU-ish termcap</bf> (strictly speaking,
  720. optional; in practice, necessary to use XFree86 binaries) it also
  721. needs to be built from source, but shouldn't require anything more
  722. complex than
  723.  
  724. <tscreen><verb>
  725. $ tar zxf termcap-2.0.8.tar.gz
  726. $ cd termcap-2.0.8
  727. $ make
  728. $ su
  729. # cp libtermcap.so.2.0.8 /usr/lib
  730. # ldconfig
  731. </verb></tscreen>
  732.  
  733. I recommend that you <em/don't/ <tt/make install/, as this would
  734. overwrite bits of the ncurses installation.  If you need to actually
  735. compile things against this library, as opposed to just running
  736. binaries that were made with it, think about putting the header files
  737. and static libraries somewhere nonstandard, and using <tt/-I/ and
  738. <tt/-L/ flags when you compile the said things.  The vagueness of this
  739. description should make it plain that continued use of termcap is
  740. `discouraged' unless you have a good reason.
  741.  
  742. <item> For <tt/libdb/, it goes something like:
  743.  
  744. <tscreen><verb>
  745. $ tar zxf db.1.85.tar.gz
  746. $ patch -p0 <db.patch
  747. $ cd db.1.85/PORT/linux
  748. $ make
  749. $ su
  750. # mkdir /usr/include/db
  751. # ldconfig
  752. # cp libdb.so.1.85.3 /usr/lib ; ( cd /usr/lib && ln -s libdb.so.1 libdb.so )
  753. # cp ../../include/*.h /usr/include/db
  754. </verb></tscreen>
  755.  
  756. Note that 
  757. <itemize>
  758.  
  759. <item> you're not applying <tt>PORT/linux/OTHER_PATCHES</tt>, because it's
  760. subsumed by this patch
  761.  
  762. <item> you're installing the header files somewhere other than
  763. <tt>/usr/include</tt> --- they conflict with the ones that gdbm uses.  To
  764. compile programs that want <tt/libdb/ you must add
  765. <tt>-I/usr/include/db</tt> to the C compiler's command line.
  766.  
  767. </itemize>
  768.  
  769. </enum>
  770.  
  771. <sect1> What it should look like (outline directory structure)
  772.  
  773. <p> This is a deliberately vague guide to what the files you have just
  774. installed are.  It may be useful for troubleshooting or deciding what
  775. to delete.
  776.  
  777. <sect2><tt> /lib </tt>
  778. <p><itemize>
  779.  
  780. <item>Dynamic linkers <tt/ld.so/ (a.out) and <tt/ld-linux.so.1/ (ELF).
  781. Either of these may be symlinks, but make sure that the files they
  782. point to do exist.
  783.  
  784. <item> Basic shared libraries <tt/libc.so.4/, <tt/libm.so.4/ (a.out)
  785. These are symlinks, but check that they point to real files.
  786.  
  787. <item> Basic shared libraries <tt/libc.so.5/, <tt/libm.so.5/,
  788. <tt/libdl.so.1/,<tt/libncurses.so.1/,<tt/libtermcap.so.2/, (ELF).  
  789. Again, these are symlinks.  Check the files that they point to.
  790.  
  791. </itemize>
  792.  
  793. <sect2><tt>/usr/lib</tt>
  794. <p><itemize>
  795.  
  796. <item> All the non-library files and directories that were there
  797. previously.
  798.  
  799. <item> <tt/libbfd.so*/,<tt/libdb.so*/, <tt/libgdbm.so*/, ELF shared
  800. libraries. 
  801.  
  802. <item> More symlinks.  For each library in <tt>/lib</tt> or <tt>/usr/lib</tt>,
  803. there should be a symlink in here.  The link's name should be the real
  804. filename, minus the version number.  For example, for <tt/libc/,
  805.  
  806. <tscreen><verb>
  807. lrwxrwxrwx   1 root     root           14 May  2 20:09 /lib/libc.so.5 -> libc.so.5.3.12
  808. -rwxr-xr-x   1 bin      bin        583795 Apr 25 06:15 /lib/libc.so.5.3.12
  809. lrwxrwxrwx   1 root     root           12 Oct 27  1995 /usr/lib/libc.so -> /lib/libc.so.5
  810. </verb></tscreen>
  811.  
  812. These links are used by <tt>ld</tt> at link time.
  813.  
  814. <item> <tt/libbsd.a/, <tt/libgmon.a/, <tt/libmcheck.a/,
  815. <tt/libmcheck.a/ and one <tt/lib*.a/ file for every ELF shared library
  816. in <tt>/lib</tt> and <tt>/usr/lib</tt>.  ELF static libraries.  The
  817. ones that duplicate shared libraries may not be tremendously useful
  818. for most people --- when using ELF, you can use the <tt/gcc -g/ switch
  819. with shared libraries, so there's not much reason to compile static
  820. any longer.  You <em/will/ need to keep them if you actually want to
  821. debug the libraries themselves.
  822.  
  823. <item> <tt/crt0.o/, <tt/gcrt0.o/.  a.out `start of program' files; one
  824. of these is linked as the first file in every a.out program you
  825. compile, unless you take steps to avoid it.
  826.  
  827. <item> <tt/crt1.o/, <tt/crtbegin.o/, <tt/crtbeginS.o/, <tt/crtend.o/,
  828. <tt/crtendS.o/, <tt/crti.o/, <tt/crtn.o/, <tt/gcrt1.o/.  ELF startup
  829. files.  These do similar things to <tt/*crt0.o/ above for ELF programs.
  830.  
  831. </itemize>
  832.  
  833. <sect2><tt> /usr/lib/ldscripts </tt>
  834.  
  835. <p><itemize>
  836.  
  837. <item> This is where the driver scripts for <tt/ld/ live, as the name
  838. suggests.  It should look like
  839. <tscreen><verb>
  840. $ ls /usr/lib/ldscripts/
  841. elf_i386.x      elf_i386.xs     i386coff.xn     i386linux.xbn
  842. elf_i386.xbn    elf_i386.xu     i386coff.xr     i386linux.xn
  843. elf_i386.xn     i386coff.x      i386coff.xu     i386linux.xr
  844. elf_i386.xr     i386coff.xbn    i386linux.x     i386linux.xu
  845. </verb></tscreen>
  846. </itemize>
  847.  
  848. <sect2><tt>/usr/i486-linux/bin</tt>
  849.  
  850. <p><itemize> 
  851.  
  852. <item> <tt/ar/, <tt/as/, <tt/gasp/, <tt/ld/, <tt/nm/, <tt/ranlib/,
  853. <tt/strip/.  These are all actually symlinks to the real binutils in
  854. <tt>/usr/bin</tt>
  855. </itemize>
  856.  
  857. <sect2><tt>/usr/i486-linuxaout/bin</tt>
  858.  
  859. <p><itemize> 
  860.  
  861. <item> <tt/as/ --- the a.out assembler, and <tt/gasp/, its macro preprocessor
  862.  
  863. <item> <tt/ar/, <tt/ld/, <tt/nm/, <tt/ranlib/, <tt/strip/ --- symlinks
  864. to the real binutils in <tt>/usr/bin</tt>
  865.  
  866. </itemize>
  867.  
  868. <sect2><tt>/usr/i486-linux/lib</tt>
  869.  
  870. <p><itemize>
  871. <item> <tt>ldscripts</tt> is a symlink to <tt>/usr/lib/ldscripts</tt>.
  872. </itemize>
  873.  
  874. <sect2><tt>/usr/i486-linuxaout/lib</tt>
  875. <p><itemize>
  876.  
  877. <item> <tt/lib*.so*/. a.out shared library images.  Needed to run
  878. a.out programs
  879.  
  880. <item> <tt/lib*.sa/. a.out shared library stubs.  Needed to compile
  881. a.out programs that use shared libraries.  If you don't intend to, you
  882. can safely remove these.
  883.  
  884. <item> <tt/lib*.a/. a.out static libraries.  Needed to compile static
  885. a.out programs (eg when compiling with <tt/-g/).  Again, you can
  886. delete them if you don't intend to do this.
  887.  
  888. <item> <tt/ldscripts/ is a symbolic link to <tt>/usr/lib/ldscripts</tt>
  889. </itemize>
  890.  
  891. <sect2><tt>/usr/lib/gcc-lib/i486-linux/2.7.2</tt>
  892.  
  893. <p><itemize>
  894. <item> This directory contains a version of gcc 2.7.2 set up to
  895. compile ELF programs.
  896. </itemize>
  897.  
  898. <sect2><tt>/usr/lib/gcc-lib/i486-linuxaout/2.7.2</tt>
  899.  
  900. <p><itemize>
  901. <item> This directory contains a version of gcc 2.7.2 set up to
  902. compile a.out programs, which knows about the new directory structure.
  903. If you're not going to compile anything in a.out, deleting this may
  904. free up around 4Mb.  Note that you need to keep it if you want to
  905. build unpatched 1.2 series kernels.
  906. </itemize>
  907.  
  908. <sect1> Common errors --- Don't Panic!
  909.  
  910. <p> (in large friendly letters)
  911.  
  912. <!-- FIXME: no mention of _h_errno yet -->
  913.  
  914. <descrip>
  915.  
  916. <tag/ You moved the wrong thing and now nothing runs/
  917.  
  918. You still have a shell running, though, and with a little ingenuity
  919. you can do an awful lot with shell builtins.  Remember that <tt>echo
  920. *</tt> is an acceptable substitute for <tt/ls/, and <tt/echo
  921. >>filename/ can be used to add lines to a file.  Also, don't forget
  922. that <tt/ldconfig/ is linked static.  If you moved, say, <tt/libc.so.4/ to
  923. <tt>/lib-aout</tt> mistakenly, you can do <tt/echo &dquot;/lib-aout&dquot;
  924. >>/etc/ld.so.conf ; ldconfig -v/ and be back up again.  If you moved
  925. <tt>/lib/ld.so</tt> you may be able to do <tt>sln /silly/place/ld.so
  926. /lib/ld.so</tt>, if you have a statically linked ln, and probably be
  927. back up again.
  928.  
  929. <tag><tt> bad address </tt></tag>
  930.  
  931. on attempting to run anything ELF.  You're using kernel
  932. 1.3.<em>x</em>, where <em>x</em><3.  Don't.  They're probably the
  933. buggiest Linux kernels on the planet anyway.  Upgrade to 2.0 or
  934. downgrade to 1.2.13.  Some people also report kernel panics in similar
  935. circumstances; I haven't investigated, chiefly as I can think of no
  936. reason for wanting or needing to run development kernels and not
  937. keeping up with the releases. 
  938.  
  939. <tag><tt> gcc: installation problem, cannot exec <em>something</em>: No such file or directory</tt>
  940. </tag>
  941.  
  942. when attempting to do a.out compilations (<em>something</em> is
  943. usually one of <tt>cpp</tt> or <tt>cc1</tt>).  Either it's right, or
  944. alternatively you typed
  945.  
  946. <tscreen><verb>
  947. $ gcc -b -i486-linuxaout
  948. </verb></tscreen>
  949.  
  950. when you should have typed
  951.  
  952. <tscreen><verb>
  953. $ gcc -b i486-linuxaout
  954. </verb></tscreen>
  955.  
  956. Note that the `i486' does <em>not</em> start with a dash.
  957.  
  958. <tag><tt/make: *** No targets specified and no makefile found.  Stop./</tag>
  959.  
  960. indicates that you haven't patched and recompiled <tt/make/, or that
  961. you still have an old version of it elsewhere on the system.
  962.  
  963. <tag><tt> no such file or directory: /usr/bin/gcc </tt></tag>
  964.  
  965. (or any other file that you try to run) when you know there
  966. <em>is</em> such a file.  This usually means that the ELF dynamic
  967. loader <tt>/lib/ld-linux.so.1</tt> is not installed, or is unreadable
  968. for some reason.  You should have installed it at around step 2
  969. previously.
  970.  
  971. <tag><tt> not a ZMAGIC file, skipping </tt></tag>
  972.  
  973. from <tt>ldconfig</tt>.  You have an old version of the ld.so package,
  974. so get a recent one.  Again, see step 2 of the installation.
  975.  
  976. <tag><tt> _setutent: Can't open utmp file </tt></tag>
  977.  
  978. This message is often seen in multiples of three when you start an
  979. xterm.  Go and read the FSSTND tirade near the end of the installation
  980. procedure.
  981.  
  982. </descrip>
  983.  
  984. <sect>Building programs 
  985.  
  986. <sect1> Ordinary programs
  987.  
  988. <p> To build a program in ELF, use <tt>gcc</tt> as always.  To build
  989. in a.out, use <tt>gcc -b i486-linuxaout </tt>.
  990.  
  991. <tscreen><verb>
  992. $ cat >hello.c
  993. main() { printf("hello, world\n"); }
  994. ^D
  995. $ gcc -o hello hello.c
  996. $ file hello
  997. hello: ELF 32-bit LSB executable i386 (386 and up) Version 1
  998. $ ./hello
  999. hello, world
  1000. </verb></tscreen>
  1001.  
  1002. This is perhaps an appropriate time to answer the question ``if a.out
  1003. compilers default to producing a program called <tt>a.out</tt>, what
  1004. name does an ELF compiler give its output?''.  Still <tt>a.out</tt>,
  1005. is the answer.  Boring boring boring ... <tt> :-)</tt>
  1006.  
  1007. <sect1> Building libraries
  1008.  
  1009. <p> To build <tt/libfoo.so/ as a shared library, the basic steps look
  1010. like this:
  1011.  
  1012. <tscreen><verb>
  1013. $ gcc -fPIC -c *.c
  1014. $ gcc -shared -Wl,-soname,libfoo.so.1 -o libfoo.so.1.0 *.o
  1015. $ ln -s libfoo.so.1.0 libfoo.so.1
  1016. $ ln -s libfoo.so.1 libfoo.so
  1017. $ export LD_LIBRARY_PATH=`pwd`:$LD_LIBRARY_PATH
  1018. </verb></tscreen>
  1019.  
  1020. This will generate a shared library called <tt>libfoo.so.1.0</tt>, and
  1021. the appropriate links for ld (<tt>libfoo.so</tt>) and the dynamic
  1022. linker (<tt>libfoo.so.1</tt>) to find it.  To test, we add the current
  1023. directory to <tt/LD_LIBRARY_PATH/.
  1024.  
  1025. When you're happpy that the library works, you'll have to move it to,
  1026. say, <tt>/usr/local/lib</tt>, and recreate the appropriate links.
  1027. Note that the <tt>libfoo.so</tt> link should point to
  1028. <tt>libfoo.so.1</tt>, so it doesn't need updating on every minor
  1029. version number change.  The link from <tt/libfoo.so.1/ to
  1030. <tt/libfoo.so.1.0/ is kept up to date by <tt>ldconfig</tt>, which on
  1031. most systems is run as part of the boot process.
  1032.  
  1033. <tscreen><verb>
  1034. $ su
  1035. # cp libfoo.so.1.0 /usr/local/lib
  1036. # /sbin/ldconfig
  1037. # ( cd /usr/local/lib ; ln -s libfoo.so.1 libfoo.so )
  1038. </verb></tscreen>
  1039.  
  1040. <sect1>Building in a.out
  1041.  
  1042. <p> You may have a need to continue to build programs in the old a.out
  1043. format.  For `normal' programs all you need to do to use the a.out
  1044. compiler is specify the flag <tt>-b i486-linuxaout</tt> when you call
  1045. gcc, and <tt>-m i386linux</tt> when (if) you call ld.  If you need to
  1046. build a.out DLL shared libraries still, you have my sympathy.  To the
  1047. best of my knowledge, the short answer is that it doesn't work.
  1048. Please mail me if you know different.
  1049.  
  1050. <sect>Patches and binaries
  1051.  
  1052. <p> At this point in the proceedings, you can, if you like, stop.  You
  1053. have installed everything necessary to compile and run ELF programs.
  1054.  
  1055. You may wish to rebuild programs in ELF, either for purposes of
  1056. `neatness' or to minimise memory usage.  For most end-user
  1057. applications, this is pretty simple; some packages however do assume
  1058. too much about the systems they run on, and may fail due to one or
  1059. more of:
  1060. <itemize>
  1061.  
  1062. <item>Different underscore conventions in the assembler: in an a.out
  1063. executable, external labels get <tt>_</tt> prefixed to them; in an ELF
  1064. executable, they don't.  This makes no difference until you start
  1065. integrating hand-written assembler: all the labels of the form
  1066. <tt>_foo</tt> must be translated to <tt>foo</tt>, or (if you want to
  1067. be portable about it) to <tt/EXTERNAL(foo)/ where <tt/EXTERNAL/ is
  1068. some macro which returns either its argument (if <tt/__ELF__/ is
  1069. defined) or <tt/_/ concatenated with its argument if not.
  1070.  
  1071. <item>Differences in libc 5 from libc 4.  The interface to the locale
  1072. support has changed, for one.
  1073.  
  1074. <item>The application or build process depending on knowledge of the
  1075. binary format used --- emacs, for example, dumps its memory image to
  1076. disk in executable format, so obviously needs to know what format your
  1077. executables are in.
  1078.  
  1079. <item>The application consists of or includes shared libraries (X11 is
  1080. the obvious example).  These will obviously need changes to accomodate
  1081. the different method of shared library creation in ELF.
  1082.  
  1083. </itemize>
  1084.  
  1085. Anyway, here are two lists: the first is of programs that needed
  1086. changing for ELF where the changes have been made (i.e. that you will
  1087. need new versions of to compile as ELF), and the second is of programs
  1088. that still need third-party patches of some kind.
  1089.  
  1090. <sect1>Upgrade:
  1091. <p>
  1092. <itemize> 
  1093.  
  1094. <item> <bf>Dosemu</bf>.  Nowadays, dosemu runs with ELF.  You'll need
  1095. to monkey with the Makefile.  Current versions of dosemu are available
  1096. from <url url="ftp://tsx-11.mit.edu/pub/linux/ALPHA/dosemu/">
  1097.  
  1098. <item> <bf>e2fsutils</bf>.  The Utilities for the Second Extended File
  1099. System versions 0.5c and later compile unchanged in ELF.
  1100.  
  1101. <item> <bf>Emacs</bf>.  There are two potential problems here.  (i)
  1102. Emacs has a rather odd build procedure that involves running a minimal
  1103. version of itself, loading in all the useful bits as lisp, then
  1104. dumping its memory image back to disk as an executable file.  (FSF)
  1105. Emacs 19.29 and XEmacs 19.12 (formerly Lucid Emacs) can both detect
  1106. whether you are compiling as ELF and Do The Right Thing automatically.
  1107. (ii) If you build some versions of emacs against ncurses, it will fail
  1108. unless you first edit <tt>src/s/linux.h</tt> in the emacs distribution
  1109. to add the line <tt/#define TERMINFO/ somewhere near the top.  This is
  1110. not necessary for 19.31, but is for XEmacs 19.13.  Apparently it will
  1111. be fixed in 19.14.
  1112.  
  1113. <item> <bf>gdb 4.16</bf>.  Your existing copy of gdb will continue to
  1114. work just as well as it always has done in the past, but the shared
  1115. library support in 4.16 is a lot better, so if you want to debug
  1116. programs that do weird things in that area, this is a good upgrade.
  1117.  
  1118. <item> <bf>The Kernel</bf>.  Kernel versions 2.0 and greater work fine
  1119. with ELF; you have to say `yes' to both of
  1120.  
  1121. <tscreen><verb>
  1122. Kernel support for ELF binaries (CONFIG_BINFMT_ELF) [Y/m/n/?]
  1123. Compile kernel as ELF - if your GCC is ELF-GCC (CONFIG_KERNEL_ELF) [Y/n/?]
  1124. </verb></tscreen>
  1125.  
  1126. when you run <tt/make config/ (this is also the case for most of the
  1127. 1.3 series).  If you are using 1.2 still, see the `patch' list below.
  1128.  
  1129. <item> <bf>perl 5</bf>.  Perl 5.001m and later will compile
  1130. unchanged on an ELF system, complete with dynamic loading.  Current
  1131. versions of Perl are available from CPAN (Comprehensive Perl Archive
  1132. Network) sites: see <url
  1133. url="ftp://ftp.funet.fi/pub/mirrors/perl/CPAN"> for the closest one to
  1134. you.
  1135.  
  1136. <item><bf>ps</bf> and <bf>top</bf>.  Procps 0.98 and greater will work
  1137. with ELF (earlier versions also work, but can't read the kernel to
  1138. find WCHAN names, if you care about them).  Note that 2.0 series
  1139. kernels require procps 0.99a or greater anyway.
  1140.  
  1141. <item> The <tt/cal/ program in <bf>util-linux 2.2</bf> doesn't work.
  1142. Upgrade to <url url="ftp://tsx-11.mit.edu/pub/linux/packages/utils"
  1143. name="version 2.5"> or later.  
  1144.  
  1145. <item> <Bf/Mosaic/.  I don't have the facilities to build this myself,
  1146. but the Mosaic 2.7b1 binary available from NCSA comes in ELF.  It has
  1147. been linked against an odd X setup though, with the result that on
  1148. normal systems it will complain about not finding <tt/libXpm.so.4.5/.
  1149. The simple fix is to edit it carefully with emacs or another editor
  1150. that copes with binary files.  Find the occurence of the string
  1151. <tt/libXpm.so.4.5^@/ (where <tt/^@/ is a NUL --- ASCII zero ---
  1152. character), delete the <tt/.5/ and add two more characters after the NUL to
  1153. aviod changing the file length.
  1154.  
  1155. </itemize>
  1156.  
  1157. <sect1> Patch
  1158. <p>
  1159. <itemize>
  1160.  
  1161. <item> <bf>file</bf>.  This works anyway, but can be improved: <url
  1162. url="ftp://ftp.uk.linux.org/pub/Linux/libc/non-core/file.patch"> adds
  1163. support for identifying stripped and mixed-endian ELF binaries.
  1164. <!-- FIXME: is this still necessary, and where is file src anyway? -->
  1165.  
  1166. <item> <tt>make-3.74</tt> --- either get the source code from a GNU
  1167. site and apply the patch that comes with the libc-5.3.12 release
  1168. notes, or get the binary <tt/make-3.74.gz/ from <tt/tsx-11/.  There is
  1169. a bug in GNU make which only manifests with new ELF libc versions ---
  1170. it's actually a dependency on a bug in old versions of the GNU libc,
  1171. which was also present in Linux libc until recently.  If you keep your
  1172. old a.out <tt/make/ program it will continue to work, but if you want
  1173. an ELF one you need the patch.
  1174.  
  1175. The GNU Make developers know about the bug, and one day will release a
  1176. fixed version.
  1177.  
  1178. <item> <bf>The 1.2.x Kernel</bf>.  You have three options:
  1179.  
  1180. <enum>
  1181. <item> Patch the Makefile slightly to use the a.out compiler.  <tt>cd
  1182. /usr/src/linux/</tt>, cut the following patch out, and feed it into
  1183. <tt/patch -p1/.  Or just edit the Makefile manually using this as a
  1184. guide; it's clear enough (delete the lines marked with a <tt/-/ and
  1185. add the ones with a <tt/+/.
  1186.  
  1187. <tscreen><verb>
  1188. diff -u linux-1.2.13/Makefile.orig linux/Makefile
  1189. --- linux-1.2.13/Makefile.orig    Wed Aug 16 20:53:26 1995
  1190. +++ linux/Makefile    Fri Dec  8 16:19:49 1995
  1191. @@ -12,9 +12,9 @@
  1192.  TOPDIR := $(shell if [ "$$PWD" != "" ]; then echo $$PWD; else pwd; fi)
  1193.  
  1194. -AS     =as
  1195. -LD     =ld
  1196. -HOSTCC =gcc -I$(TOPDIR)/include
  1197. -CC     =gcc -D__KERNEL__ -I$(TOPDIR)/include
  1198. +AS     =/usr/i486-linuxaout/bin/as
  1199. +LD     =ld  -m i386linux
  1200. +HOSTCC =gcc -b i486-linuxaout -I$(TOPDIR)/include
  1201. +CC     =gcc -b i486-linuxaout -D__KERNEL__ -I$(TOPDIR)/include
  1202.  MAKE   =make
  1203.  CPP    =$(CC) -E
  1204.  AR     =ar
  1205. </verb></tscreen>
  1206.  
  1207. Alternatively,
  1208.  
  1209. <item> Apply H J Lu's patch which allows compiling the kernel in ELF
  1210. (and also adds the ability to do ELF core dumps).  This can be had
  1211. from <url
  1212. url="ftp://ftp.cdrom.com/pub/linux/slackware_source/kernel-source/v1.2/linuxelf-1.2.13.diff.gz">.
  1213.  
  1214. If you are using an ELF distribution (RedHat 2.1, Slackware 3) which
  1215. comes with a 1.2 series kernel, you will probably find that this patch
  1216. or one similar has been applied already.
  1217.  
  1218. The best idea, hoever, is probably
  1219.  
  1220. <item> Upgrade to 2.0!  1.2 was never really intended for ELF anyway.
  1221.  
  1222. </enum>
  1223.  
  1224. You will have other problems compiling 1.2.13 with gcc 2.7.2 and above; 
  1225. there was a bug in <tt>asm/io.h</tt> which is only detected by gcc
  1226. 2.7.2.  You will need the patch <url url="ftp://ftp.uk.linux.org/pub/Linux/libc/misc/io.h">.
  1227.  
  1228. </itemize>
  1229.  
  1230. <sect>Further information
  1231.  
  1232. <p> 
  1233. <itemize>
  1234.  
  1235. <item>The <url url="GCC-HOWTO.html" name="GCC-HOWTO"> contains much
  1236. useful information about development on Linux (at least, I think it
  1237. does; I maintain it).  It should be available from the same place as
  1238. you found this, which is why the link above is relative.
  1239.  
  1240. <item>The <tt>linux-gcc</tt> mailing list (which is also the
  1241. <tt/linux.dev.gcc/ newsgroup, if you have a <tt/linux.*/ news feed) is
  1242. really the best place to see what's happening, usually without even
  1243. posting to it.  Remember, it's not Usenet, so keep the questions down
  1244. unless you're actually developing.  For instructions on joining the
  1245. mailing list, mail a message containing the word <tt>help</tt> to
  1246. <tt>majordomo@vger.rutgers.edu</tt>.  Archives of the list are at <url
  1247. url="http://www.linux.ncm.com/linux-gcc/">.
  1248.  
  1249. <item> There's a certain amount of information about what the
  1250. linux-gcc list is doing at my <url
  1251. url="http://ftp.uk.linux.org/~barlow/linux/gcc-list.html"
  1252. name="linux-gcc web page">, when I remember to update it.  This also
  1253. has a link to the latest version of this HOWTO, and the patches it
  1254. refers to.  For US people and others with poor links to UK academic
  1255. sites (that's nearly everyone outside of UK academia), this is all
  1256. mirrored at
  1257. <url url="http://www.blackdown.org/elf/elf.html">
  1258.  
  1259. <item>There's also documentation for the file format on <url
  1260. url="ftp://tsx-11.mit.edu/pub/linux/packages/GCC/ELF.doc.tar.gz"
  1261. name="tsx-11">.  This is probably of most use to people who want to
  1262. understand, debug or rewrite programs that deal directly with binary
  1263. objects.
  1264.  
  1265. <item>H J Lu's document <url name="ELF: From The Programmer's
  1266. Perspective"
  1267. url="ftp://tsx-11.mit.edu/pub/linux/packages/GCC/elf.latex.tar.gz">
  1268. contains much useful and more detailed information on programming with
  1269. ELF.  If you aren't LaTeX-capable, it is also available as PostScript.
  1270.  
  1271. <item>Information about the <bf/ncurses/ library and the terminfo
  1272. database is available from <url
  1273. url="http://www.ccil.org/~esr/ncurses.html" name="Eric Raymond's
  1274. ncurses resource page">.
  1275.  
  1276. <item> There is a manual page covering <tt>dlopen(3)</tt> and related
  1277. functions, which is supplied with the <tt>ld.so</tt> package.
  1278.  
  1279. </itemize>
  1280.  
  1281. <sect> Miscellanities
  1282.  
  1283. <sect1> Feedback
  1284.  
  1285. <p> is welcomed.  Mail me at <htmlurl
  1286. url="mailto:daniel.barlow@linux.org"
  1287. name="daniel.barlow@linux.org">.  My PGP public key (ID 5F263625) is
  1288. available from my <url url="http://ftp.uk.linux.org/~barlow/"
  1289. name="web pages">, if you feel the need to be secretive about things.
  1290.  
  1291. If you have a question that you feel this document should have
  1292. answered and doesn't, mail me.  If you have a question which probably
  1293. shouldn't be answered here but you think I might know the answer
  1294. anyway, you might want to try posting to an appropriate
  1295. <tt/comp.os.linux.*/ newsgroup first; I usually answer mail
  1296. eventually, but I have been known to lose it on occasion.
  1297.  
  1298. Anyone found adding my name to junk email lists will pay dearly for it.
  1299.  
  1300. <sect1> Translations
  1301.  
  1302. <p> If you wish to translate this document, please go right ahead, but
  1303. do tell me about it!  The chances are (sadly) several hundred to one
  1304. against that I speak the language you wish to translate to, but that
  1305. aside I am happy to help in whatever way I can.
  1306.  
  1307. <p> Translations that I know of are:
  1308.  
  1309. <itemize>
  1310.  
  1311. <item> <url url="http://www.psico.unipd.it/ildp/docs/HOWTO/ELF-HOWTO.html"
  1312. name="Italian">, by Favro Renata.  (Other HOWTOs are also available in Italian from
  1313. <url url="http://www.psico.unipd.it/ildp/docs/HOWTO/INDEX.html">.
  1314.  
  1315. <item> Kojima Mitsuhiro has produced a Japanese translation, available
  1316. from <url url="http://jf.gee.kyoto-u.ac.jp/JF/index.html">. 
  1317.  
  1318. </itemize>
  1319.  
  1320. <sect1> Legal bits
  1321.  
  1322. <p> All trademarks used in this document are acknowledged as being
  1323. owned by their respective owners.  Yow!
  1324.  
  1325. <p> The right of Daniel Barlow to be identified as the author of this
  1326. work has been asserted in accordance with sections 77 and 78 of the
  1327. Copyright Designs and Patents Act 1988.
  1328.  
  1329. This document is copyright (C) 1996 Daniel Barlow
  1330. <tt/<daniel.barlow@linux.org>/ It may be reproduced and
  1331. distributed in whole or in part, in any medium physical or electronic,
  1332. as long as this copyright notice is retained on all copies. Commercial
  1333. redistribution is allowed and encouraged; however, the author would
  1334. like to be notified of any such distributions.
  1335.  
  1336. All translations, derivative works, or aggregate works incorporating
  1337. any Linux HOWTO documents must be covered under this copyright notice.
  1338. That is, you may not produce a derivative work from a HOWTO and impose
  1339. additional restrictions on its distribution. Exceptions to these rules
  1340. may be granted under certain conditions; please contact the Linux
  1341. HOWTO coordinator at the address given below.
  1342.  
  1343. In short, we wish to promote dissemination of this information through
  1344. as many channels as possible. However, we do wish to retain copyright
  1345. on the HOWTO documents, and would like to be notified of any plans to
  1346. redistribute the HOWTOs.
  1347.  
  1348. If you have questions, please contact Greg Hankins, the Linux HOWTO
  1349. coordinator, at <tt/gregh@sunsite.unc.edu/.
  1350.  
  1351. </article>
  1352.