{
"mode": "info",
"parameter": "automake-history",
"section": "",
"url": "https://www.chedong.com/phpMan.php/info/automake-history/json",
"generated": "2026-07-06T05:23:06Z",
"sections": {
"File: automake-history.info, Node: Top, Next: Timeline, Up: (dir)": {
"content": "",
"subsections": []
},
"Brief History of Automake": {
"content": "",
"subsections": []
},
"This manual describes (part of) the history of GNU Automake, a program": {
"content": "that creates GNU standards-compliant Makefiles from template files.\n\nCopyright (C) 1995-2021 Free Software Foundation, Inc.\n\nPermission is granted to copy, distribute and/or modify this\ndocument under the terms of the GNU Free Documentation License,\nVersion 1.3 or any later version published by the Free Software\nFoundation; with no Invariant Sections, with no Front-Cover texts,\nand with no Back-Cover Texts. A copy of the license is included in\nthe section entitled \"GNU Free Documentation License.\"\n\n* Menu:\n\n* Timeline:: The Automake story.\n* Dependency Tracking Evolution:: Evolution of Automatic Dependency Tracking\n* Releases:: Release statistics\n* Copying This Manual:: How to make copies of this manual\n\n-- The Detailed Node Listing --\n",
"subsections": []
},
"Evolution of Automatic Dependency Tracking": {
"content": "* First Take on Dependencies:: Precomputed dependency tracking\n* Dependencies As Side Effects:: Update at developer compile time\n* Dependencies for the User:: Update at user compile time\n* Techniques for Dependencies:: Alternative approaches\n",
"subsections": []
},
"Techniques for Computing Dependencies": {
"content": "* Recommendations for Tool Writers::\n* Future Directions for Dependencies::\n",
"subsections": []
},
"Copying This Manual": {
"content": "* GNU Free Documentation License:: License for copying this manual\n\n",
"subsections": []
},
"File: automake-history.info, Node: Timeline, Next: Dependency Tracking Evolution, Prev: Top, Up: Top": {
"content": "",
"subsections": []
},
"1 Timeline": {
"content": "1994-09-19 First CVS commit.\n\nIf we can trust the CVS repository, David J. MacKenzie (djm)\nstarted working on Automake (or AutoMake, as it was spelt then)\nthis Monday.\n\nThe first version of the 'automake' script looks as follows.\n\n#!/bin/sh\n\nstatus=0\n\nfor makefile\ndo\nif test ! -f ${makefile}.am; then\necho \"automake: ${makefile}.am: No such honkin' file\"\nstatus=1\ncontinue\nfi\n\nexec 4> ${makefile}.in\n\ndone\n\nFrom this you can already see that Automake will be about reading\n'*.am' file and producing '*.in' files. You cannot see anything\nelse, but if you also know that David is the one who created\nAutoconf two years before you can guess the rest.\n\nSeveral commits follow, and by the end of the day Automake is\nreported to work for GNU fileutils and GNU m4.\n\nThe modus operandi is the one that is still used today: variable\nassignments in 'Makefile.am' files trigger injections of precanned\n'Makefile' fragments into the generated 'Makefile.in'. The use of\n'Makefile' fragments was inspired by the 4.4BSD 'make' and include\nfiles, however Automake aims to be portable and to conform to the\nGNU standards for 'Makefile' variables and targets.\n\nAt this point, the most recent release of Autoconf is version 1.11,\nand David is preparing to release Autoconf 2.0 in late October. As\na matter of fact, he will barely touch Automake after September.\n\n1994-11-05 David MacKenzie's last commit.\n\nAt this point Automake is a 200 line portable shell script, plus\n332 lines of 'Makefile' fragments. In the 'README', David states\nhis ambivalence between \"portable shell\" and \"more appropriate\nlanguage\":\n\nI wrote it keeping in mind the possibility of it becoming an\nAutoconf macro, so it would run at configure-time. That would\nslow configuration down a bit, but allow users to modify the\nMakefile.am without needing to fetch the AutoMake package.\nAnd, the Makefile.in files wouldn't need to be distributed.\nBut all of AutoMake would. So I might reimplement AutoMake in\nPerl, m4, or some other more appropriate language.\n\nAutomake is described as \"an experimental Makefile generator\".\nThere is no documentation. Adventurous users are referred to the\nexamples and patches needed to use Automake with GNU m4 1.3,\nfileutils 3.9, time 1.6, and development versions of find and\nindent.\n\nThese examples seem to have been lost. However at the time of\nwriting (10 years later in September, 2004) the FSF still\ndistributes a package that uses this version of Automake: check out\nGNU termutils 2.0.\n\n1995-11-12 Tom Tromey's first commit.\n\nAfter one year of inactivity, Tom Tromey takes over the package.\nTom was working on GNU cpio back then, and doing this just for fun,\nhaving trouble finding a project to contribute to. So while\nhacking he wanted to bring the 'Makefile.in' up to GNU standards.\nThis was hard, and one day he saw Automake on\n, grabbed it and tried it out.\n\nTom didn't talk to djm about it until later, just to make sure he\ndidn't mind if he made a release. He did a bunch of early releases\nto the Gnits folks.\n\nGnits was (and still is) totally informal, just a few GNU friends\nwho Franc,ois Pinard knew, who were all interested in making a\ncommon infrastructure for GNU projects, and shared a similar\noutlook on how to do it. So they were able to make some progress.\nIt came along with Autoconf and extensions thereof, and then\nAutomake from David and Tom (who were both gnitsians). One of\ntheir ideas was to write a document paralleling the GNU standards,\nthat was more strict in some ways and more detailed. They never\nfinished the GNITS standards, but the ideas mostly made their way\ninto Automake.\n\n1995-11-23 Automake 0.20\n\nBesides introducing automatic dependency tracking (*note Dependency\nTracking Evolution::), this version also supplies a 9-page manual.\n\nAt this time 'aclocal' and 'AMINITAUTOMAKE' did not exist, so\nmany things had to be done by hand. For instance, here is what a\nconfigure.in (this is the former name of the 'configure.ac' we use\ntoday) must contain in order to use Automake 0.20:\n\nPACKAGE=cpio\nVERSION=2.3.911\nACDEFINEUNQUOTED(PACKAGE, \"$PACKAGE\")\nACDEFINEUNQUOTED(VERSION, \"$VERSION\")\nACSUBST(PACKAGE)\nACSUBST(VERSION)\nACARGPROGRAM\nACPROGINSTALL\n\n(Today all of the above is achieved by 'ACINIT' and\n'AMINITAUTOMAKE'.)\n\nHere is how programs are specified in 'Makefile.am':\n\nPROGRAMS = hello\nhelloSOURCES = hello.c\n\nThis looks pretty much like what we do today, except the 'PROGRAMS'\nvariable has no directory prefix specifying where 'hello' should be\ninstalled: all programs are installed in '$(bindir)'.\n'LIBPROGRAMS' can be used to specify programs that must be built\nbut not installed (it is called 'noinstPROGRAMS' nowadays).\n\nPrograms can be built conditionally using 'ACSUBST'itutions:\n\nPROGRAMS = @progs@\nAMPROGRAMS = foo bar baz\n\n('AMPROGRAMS' has since then been renamed to 'EXTRAPROGRAMS'.)\n\nSimilarly scripts, static libraries, and data can be built and\ninstalled using the 'LIBRARIES', 'SCRIPTS', and 'DATA' variables.\nHowever 'LIBRARIES' were treated a bit specially in that Automake\ndid automatically supply the 'lib' and '.a' prefixes. Therefore to\nbuild 'libcpio.a', one had to write\n\nLIBRARIES = cpio\ncpioSOURCES = ...\n\nExtra files to distribute must be listed in 'DISTOTHER' (the\nancestor of 'EXTRADIST'). Also extra directories that are to be\ndistributed should appear in 'DISTSUBDIRS', but the manual\ndescribes this as a temporary ugly hack (today extra directories\nshould also be listed in 'EXTRADIST', and 'DISTSUBDIRS' is used\nfor another purpose, *note Conditional Subdirectories:\n(automake)Conditional Subdirectories.).\n\n1995-11-26 Automake 0.21\n\nIn less time than it takes to cook a frozen pizza, Tom rewrites\nAutomake using Perl. At this time Perl 5 is only one year old, and\nPerl 4.036 is in use at many sites. Supporting several Perl\nversions has been a source of problems through the whole history of\nAutomake.\n\nIf you never used Perl 4, imagine Perl 5 without objects, without\n'my' variables (only dynamically scoped 'local' variables), without\nfunction prototypes, with function calls that needs to be prefixed\nwith '&', etc. Traces of this old style can still be found in\ntoday's 'automake'.\n\n1995-11-28 Automake 0.22\n1995-11-29 Automake 0.23\n\nBug fixes.\n\n1995-12-08 Automake 0.24\n1995-12-10 Automake 0.25\n\nReleases are raining. 0.24 introduces the uniform naming scheme we\nuse today, i.e., 'binPROGRAMS' instead of 'PROGRAMS',\n'noinstLIBRARIES' instead of 'LIBLIBRARIES', etc. (However\n'EXTRAPROGRAMS' does not exist yet, 'AMPROGRAMS' is still in use;\nand 'TEXINFOS' and 'MANS' still have no directory prefixes.)\nAdding support for prefixes like that was one of the major ideas in\n'automake'; it has lasted pretty well.\n\nAutoMake is renamed to Automake (Tom seems to recall it was\nFranc,ois Pinard's doing).\n\n0.25 fixes a Perl 4 portability bug.\n\n1995-12-18 Jim Meyering starts using Automake in GNU Textutils.\n1995-12-31 Franc,ois Pinard starts using Automake in GNU tar.\n\n1996-01-03 Automake 0.26\n1996-01-03 Automake 0.27\n\nOf the many changes and suggestions sent by Franc,ois Pinard and\nincluded in 0.26, perhaps the most important is the advice that to\nease customization a user rule or variable definition should always\noverride an Automake rule or definition.\n\nGordon Matzigkeit and Jim Meyering are two other early contributors\nthat have been sending fixes.\n\n0.27 fixes yet another Perl 4 portability bug.\n\n1996-01-13 Automake 0.28\n\nAutomake starts scanning 'configure.in' for 'LIBOBJS' support.\nThis is an important step because until this version Automake only\nknew about the 'Makefile.am's it processed. 'configure.in' was\nAutoconf's world and the link between Autoconf and Automake had to\nbe done by the 'Makefile.am' author. For instance, if 'config.h'\nwas generated by 'configure', it was the package maintainer's\nresponsibility to define the 'CONFIGHEADER' variable in each\n'Makefile.am'.\n\nSucceeding releases will rely more and more on scanning\n'configure.in' to better automate the Autoconf integration.\n\n0.28 also introduces the 'AUTOMAKEOPTIONS' variable and the\n'--gnu' and '--gnits' options, the latter being stricter.\n\n1996-02-07 Automake 0.29\n\nThanks to 'configure.in' scanning, 'CONFIGHEADER' is gone, and\nrebuild rules for 'configure'-generated file are automatically\noutput.\n\n'TEXINFOS' and 'MANS' converted to the uniform naming scheme.\n\n1996-02-24 Automake 0.30\n\nThe test suite is born. It contains 9 tests. From now on test\ncases will be added pretty regularly (*note Releases::), and this\nproved to be really helpful later on.\n\n'EXTRAPROGRAMS' finally replaces 'AMPROGRAMS'.\n\nAll the third-party Autoconf macros, written mostly by Franc,ois\nPinard (and later Jim Meyering), are distributed in Automake's\nhand-written 'aclocal.m4' file. Package maintainers are expected\nto extract the necessary macros from this file. (In previous\nversions you had to copy and paste them from the manual...)\n\n1996-03-11 Automake 0.31\n\nThe test suite in 0.30 was run via a long 'check-local' rule. Upon\nUlrich Drepper's suggestion, 0.31 makes it an Automake rule output\nwhenever the 'TESTS' variable is defined.\n\n'DISTOTHER' is renamed to 'EXTRADIST', and the 'check' prefix is\nintroduced. The syntax is now the same as today.\n\n1996-03-15 Gordon Matzigkeit starts writing libtool.\n\n1996-04-27 Automake 0.32\n\n'-hook' targets are introduced; an idea from Dieter Baron.\n\n'*.info' files, which were output in the build directory are now\nbuilt in the source directory, because they are distributed. It\nseems these files like to move back and forth as that will happen\nagain in future versions.\n\n1996-05-18 Automake 0.33\n\nGord Matzigkeit's main two contributions:\n\n* very preliminary libtool support\n* the distcheck rule\n\nAlthough they were very basic at this point, these are probably\namong the top features for Automake today.\n\nJim Meyering also provides the infamous 'jmMAINTAINERMODE', since\nthen renamed to 'AMMAINTAINERMODE' and abandoned by its author\n(*note maintainer-mode: (automake)maintainer-mode.).\n\n1996-05-28 Automake 1.0\n\nAfter only six months of heavy development, the 'automake' script\nis 3134 lines long, plus 973 lines of 'Makefile' fragments. The\npackage has 30 pages of documentation, and 38 test cases.\n'aclocal.m4' contains 4 macros.\n\nFrom now on and until version 1.4, new releases will occur at a\nrate of about one a year. 1.1 did not exist, actually 1.1b to 1.1p\nhave been the name of beta releases for 1.2. This is the first\ntime Automake uses suffix letters to designate beta releases, a\nhabit that lasts.\n\n1996-10-10 Kevin Dalley packages Automake 1.0 for Debian GNU/Linux.\n\n1996-11-26 David J. MacKenzie releases Autoconf 2.12.\n\nBetween June and October, the Autoconf development is almost\nstalled. Roland McGrath has been working at the beginning of the\nyear. David comes back in November to release 2.12, but he won't\ntouch Autoconf anymore after this year, and Autoconf then really\nstagnates. The desolate Autoconf 'ChangeLog' for 1997 lists only 7\ncommits.\n\n1997-02-28 list alive\n\nThe mailing list is announced as follows:\nI've created the \"automake\" mailing list. It is\n\"automake@gnu.ai.mit.edu\". Administrivia, as always, to\nautomake-request@gnu.ai.mit.edu.\n\nThe charter of this list is discussion of automake, autoconf, and\nother configuration/portability tools (e.g., libtool). It is expected\nthat discussion will range from pleas for help all the way up to\npatches.\n\nThis list is archived on the FSF machines. Offhand I don't know if\nyou can get the archive without an account there.\n\nThis list is open to anybody who wants to join. Tell all your\nfriends!\n-- Tom Tromey\n\nBefore that people were discussing Automake privately, on the Gnits\nmailing list (which is not public either), and less frequently on\n'gnu.misc.discuss'.\n\n'gnu.ai.mit.edu' is now 'gnu.org', in case you never noticed. The\narchives of the early years of the 'automake@gnu.org' list have\nbeen lost, so today it is almost impossible to find traces of\ndiscussions that occurred before 1999. This has been annoying more\nthan once, as such discussions can be useful to understand the\nrationale behind a piece of uncommented code that was introduced\nback then.\n\n1997-06-22 Automake 1.2\n\nAutomake developments continues, and more and more new Autoconf\nmacros are required. Distributing them in 'aclocal.m4' and\nrequiring people to browse this file to extract the relevant macros\nbecomes uncomfortable. Ideally, some of them should be contributed\nto Autoconf so that they can be used directly, however Autoconf is\ncurrently inactive. Automake 1.2 consequently introduces 'aclocal'\n('aclocal' was actually started on 1996-07-28), a tool that\nautomatically constructs an 'aclocal.m4' file from a repository of\nthird-party macros. Because Autoconf has stalled, Automake also\nbecomes a kind of repository for such third-party macros, even\nmacros completely unrelated to Automake (for instance macros that\nfix broken Autoconf macros).\n\nThe 1.2 release contains 20 macros, including the\n'AMINITAUTOMAKE' macro that simplifies the creation of\n'configure.in'.\n\nLibtool is fully supported using '*LTLIBRARIES'.\n\nThe missing script is introduced by Franc,ois Pinard; it is meant to\nbe a better solution than 'AMMAINTAINERMODE' (*note\nmaintainer-mode: (automake)maintainer-mode.).\n\nConditionals support was implemented by Ian Lance Taylor. At the\ntime, Tom and Ian were working on an internal project at Cygnus.\nThey were using ILU, which is pretty similar to CORBA. They wanted\nto integrate ILU into their build, which was all 'configure'-based,\nand Ian thought that adding conditionals to 'automake' was simpler\nthan doing all the work in 'configure' (which was the standard at\nthe time). So this was actually funded by Cygnus.\n\nThis very useful but tricky feature will take a lot of time to\nstabilize. (At the time this text is written, there are still\nprimaries that have not been updated to support conditional\ndefinitions in Automake 1.9.)\n\nThe 'automake' script has almost doubled: 6089 lines of Perl, plus\n1294 lines of 'Makefile' fragments.\n\n1997-07-08 Gordon Matzigkeit releases Libtool 1.0.\n\n1998-04-05 Automake 1.3\n\nThis is a small advance compared to 1.2. It adds support for\nassembly, and preliminary support for Java.\n\nPerl 5.00404 is out, but fixes to support Perl 4 are still\nregularly submitted whenever Automake breaks it.\n\n1998-09-06 'sourceware.cygnus.com' is on-line.\n\nSourceware was setup by Jason Molenda to host open source projects.\n\n1998-09-19 Automake CVS repository moved to 'sourceware.cygnus.com'\n1998-10-26 'sourceware.cygnus.com' announces it hosts Automake:\nAutomake is now hosted on 'sourceware.cygnus.com'. It has a\npublicly accessible CVS repository. This CVS repository is a copy\nof the one Tom was using on his machine, which in turn is based on\na copy of the CVS repository of David MacKenzie. This is why we\nstill have to full source history. (Automake was on Sourceware\nuntil 2007-10-29, when it moved to a git repository on\n'savannah.gnu.org', but the Sourceware host had been renamed to\n'sources.redhat.com'.)\n\nThe oldest file in the administrative directory of the CVS\nrepository that was created on Sourceware is dated 1998-09-19,\nwhile the announcement that 'automake' and 'autoconf' had joined\n'sourceware' was made on 1998-10-26. They were among the first\nprojects to be hosted there.\n\nThe heedful reader will have noticed Automake was exactly 4 years\nold on 1998-09-19.\n\n1999-01-05 Ben Elliston releases Autoconf 2.13.\n\n1999-01-14 Automake 1.4\n\nThis release adds support for Fortran 77 and for the 'include'\nstatement. Also, '+=' assignments are introduced, but it is still\nquite easy to fool Automake when mixing this with conditionals.\n\nThese two releases, Automake 1.4 and Autoconf 2.13 make a duo that\nwill be used together for years.\n\n'automake' is 7228 lines, plus 1591 lines of Makefile fragment, 20\nmacros (some 1.3 macros were finally contributed back to Autoconf),\n197 test cases, and 51 pages of documentation.\n\n1999-03-27 The 'user-dep-branch' is created on the CVS repository.\n\nThis implements a new dependency tracking schemed that should be\nable to handle automatic dependency tracking using any compiler\n(not just gcc) and any make (not just GNU 'make'). In addition,\nthe new scheme should be more reliable than the old one, as\ndependencies are generated on the end user's machine. Alexandre\nOliva creates depcomp for this purpose.\n\n*Note Dependency Tracking Evolution::, for more details about the\nevolution of automatic dependency tracking in Automake.\n\n1999-11-21 The 'user-dep-branch' is merged into the main trunk.\n\nThis was a huge problem since we also had patches going in on the\ntrunk. The merge took a long time and was very painful.\n\n2000-05-10\n\nSince September 1999 and until 2003, Akim Demaille will be\nzealously revamping Autoconf.\n\nI think the next release should be called \"3.0\".\nLet's face it: you've basically rewritten autoconf.\nEvery weekend there are 30 new patches.\nI don't see how we could call this \"2.15\" with a straight\nface.\n- Tom Tromey on \n\nActually Akim works like a submarine: he will pile up patches while\nhe works off-line during the weekend, and flush them in batch when\nhe resurfaces on Monday.\n\n2001-01-24\n\nOn this Wednesday, Autoconf 2.49c, the last beta before Autoconf\n2.50 is out, and Akim has to find something to do during his\nweek-end :)\n\n2001-01-28\n\nAkim sends a batch of 14 patches to .\n\nAiieeee! I was dreading the day that the Demaillator turned\nhis sights on automake... and now it has arrived! - Tom\nTromey\n\nIt's only the beginning: in two months he will send 192 patches.\nThen he would slow down so Tom can catch up and review all this.\nInitially Tom actually read all of these patches, then he probably\ntrustingly answered OK to most of them, and finally gave up and let\nAkim apply whatever he wanted. There was no way to keep up with\nthat patch rate.\n\nAnyway the patch below won't apply since it predates Akim's\nsourcequake; I have yet to figure where the relevant passage\nhas been moved :) - Alexandre Duret-Lutz\n\nAll of these patches were sent to and discussed on\n, so subscribed users were literally drowning in\ntechnical mails. Eventually, the \nmailing list was created in May.\n\nYear after year, Automake had drifted away from its initial design:\nconstruct 'Makefile.in' by assembling various 'Makefile' fragments.\nIn 1.4, lots of 'Makefile' rules are being emitted at various\nplaces in the 'automake' script itself; this does not help ensuring\na consistent treatment of these rules (for instance making sure\nthat user-defined rules override Automake's own rules). One of\nAkim's goal was moving all of these hard-coded rules to separate\n'Makefile' fragments, so the logic could be centralized in a\n'Makefile' fragment processor.\n\nAnother significant contribution of Akim is the interface with the\n\"trace\" feature of Autoconf. The way to scan 'configure.in' at\nthis time was to read the file and grep the various macro of\ninterest to Automake. Doing so could break in many unexpected\nways; 'automake' could miss some definition (for instance\n'ACSUBST([$1], [$2])' where the arguments are known only when M4\nis run), or conversely it could detect some macro that was not\nexpanded (because it is called conditionally). In the CVS version\nof Autoconf, Akim had implemented the '--trace' option, which\nprovides accurate information about where macros are actually\ncalled and with what arguments. Akim will equip Automake with a\nsecond 'configure.in' scanner that uses this '--trace' interface.\nSince it was not sensible to drop the Autoconf 2.13 compatibility\nyet, this experimental scanner was only used when an environment\nvariable was set, the traditional grep-scanner being still the\ndefault.\n\n2001-04-25 Gary V. Vaughan releases Libtool 1.4\n\nIt has been more than two years since Automake 1.4, CVS Automake\nhas suffered lot's of heavy changes and still is not ready for\nrelease. Libtool 1.4 had to be distributed with a patch against\nAutomake 1.4.\n\n2001-05-08 Automake 1.4-p1\n2001-05-24 Automake 1.4-p2\n\nGary V. Vaughan, the principal Libtool maintainer, makes a \"patch\nrelease\" of Automake:\n\nThe main purpose of this release is to have a stable automake\nwhich is compatible with the latest stable libtool.\n\nThe release also contains obvious fixes for bugs in Automake 1.4,\nsome of which were reported almost monthly.\n\n2001-05-21 Akim Demaille releases Autoconf 2.50\n\n2001-06-07 Automake 1.4-p3\n2001-06-10 Automake 1.4-p4\n2001-07-15 Automake 1.4-p5\n\nGary continues his patch-release series. These also add support\nfor some new Autoconf 2.50 idioms. Essentially, Autoconf now\nadvocates 'configure.ac' over 'configure.in', and it introduces a\nnew syntax for 'ACOUTPUT'ing files.\n\n2001-08-23 Automake 1.5\n\nA major and long-awaited release, that comes more than two years\nafter 1.4. It brings many changes, among which:\n* The new dependency tracking scheme that uses 'depcomp'. Aside\nfrom the improvement on the dependency tracking itself (*note\nDependency Tracking Evolution::), this also streamlines the\nuse of 'automake'-generated 'Makefile.in's as the\n'Makefile.in's used during development are now the same as\nthose used in distributions. Before that the 'Makefile.in's\ngenerated for maintainers required GNU 'make' and GCC, they\nwere different from the portable 'Makefile' generated for\ndistribution; this was causing some confusion.\n\n* Support for per-target compilation flags.\n\n* Support for reference to files in subdirectories in most\n'Makefile.am' variables.\n\n* Introduction of the 'dist', 'nodist', and 'nobase'\nprefixes.\n* Perl 4 support is finally dropped.\n\n1.5 did break several packages that worked with 1.4. Enough so\nthat Linux distributions could not easily install the new Automake\nversion without breaking many of the packages for which they had to\nrun 'automake'.\n\nSome of these breakages were effectively bugs that would eventually\nbe fixed in the next release. However, a lot of damage was caused\nby some changes made deliberately to render Automake stricter on\nsome setup we did consider bogus. For instance, 'make distcheck'\nwas improved to check that 'make uninstall' did remove all the\nfiles 'make install' installed, that 'make distclean' did not omit\nsome file, and that a VPATH build would work even if the source\ndirectory was read-only. Similarly, Automake now rejects multiple\ndefinitions of the same variable (because that would mix very badly\nwith conditionals), and '+=' assignments with no previous\ndefinition. Because these changes all occurred suddenly after 1.4\nhad been established for more than two years, it hurt users.\n\nTo make matter worse, meanwhile Autoconf (now at version 2.52) was\nfacing similar troubles, for similar reasons.\n\n2002-03-05 Automake 1.6\n\nThis release introduced versioned installation (*note API\nVersioning: (automake)API Versioning.). This was mainly pushed by\nHavoc Pennington, taking the GNOME source tree as motive: due to\nincompatibilities between the autotools it's impossible for the\nGNOME packages to switch to Autoconf 2.53 and Automake 1.5 all at\nonce, so they are currently stuck with Autoconf 2.13 and Automake\n1.4.\n\nThe idea was to call this version 'automake-1.6', call all its\nbug-fix versions identically, and switch to 'automake-1.7' for the\nnext release that adds new features or changes some rules. This\nscheme implies maintaining a bug-fix branch in addition to the\ndevelopment trunk, which means more work from the maintainer, but\nproviding regular bug-fix releases proved to be really worthwhile.\n\nLike 1.5, 1.6 also introduced a bunch of incompatibilities,\nintentional or not. Perhaps the more annoying was the dependence\non the newly released Autoconf 2.53. Autoconf seemed to have\nstabilized enough since its explosive 2.50 release and included\nchanges required to fix some bugs in Automake. In order to upgrade\nto Automake 1.6, people now had to upgrade Autoconf too; for some\npackages it was no picnic.\n\nWhile versioned installation helped people to upgrade, it also\nunfortunately allowed people not to upgrade. At the time of\nwriting, some Linux distributions are shipping packages for\nAutomake 1.4, 1.5, 1.6, 1.7, 1.8, and 1.9. Most of these still\ninstall 1.4 by default. Some distribution also call 1.4 the\n\"stable\" version, and present \"1.9\" as the development version;\nthis does not really makes sense since 1.9 is way more solid than\n1.4. All this does not help the newcomer.\n\n2002-04-11 Automake 1.6.1\n\n1.6, and the upcoming 1.4-p6 release were the last release by Tom.\nThis one and those following will be handled by Alexandre\nDuret-Lutz. Tom is still around, and will be there until about\n1.7, but his interest into Automake is drifting away towards\nprojects like 'gcj'.\n\nAlexandre has been using Automake since 2000, and started to\ncontribute mostly on Akim's incitement (Akim and Alexandre have\nbeen working in the same room from 1999 to 2002). In 2001 and 2002\nhe had a lot of free time to enjoy hacking Automake.\n\n2002-06-14 Automake 1.6.2\n\n2002-07-28 Automake 1.6.3\n2002-07-28 Automake 1.4-p6\n\nTwo releases on the same day. 1.6.3 is a bug-fix release.\n\nTom Tromey backported the versioned installation mechanism on the\n1.4 branch, so that Automake 1.6.x and Automake 1.4-p6 could be\ninstalled side by side. Another request from the GNOME folks.\n\n2002-09-25 Automake 1.7\n\nThis release switches to the new 'configure.ac' scanner Akim was\nexperimenting in 1.5.\n\n2002-10-16 Automake 1.7.1\n2002-12-06 Automake 1.7.2\n2003-02-20 Automake 1.7.3\n2003-04-23 Automake 1.7.4\n2003-05-18 Automake 1.7.5\n2003-07-10 Automake 1.7.6\n2003-09-07 Automake 1.7.7\n2003-10-07 Automake 1.7.8\n\nMany bug-fix releases. 1.7 lasted because the development version\n(upcoming 1.8) was suffering some major internal revamping.\n\n2003-10-26 Automake on screen\n\nEpisode 49, 'Repercussions', in the third season of the 'Alias' TV\nshow is first aired.\n\nMarshall, one of the characters, is working on a computer virus\nthat he has to modify before it gets into the wrong hands or\nsomething like that. The screenshots you see do not show any\nprogram code, they show a 'Makefile.in' generated by automake...\n\n2003-11-09 Automake 1.7.9\n\n2003-12-10 Automake 1.8\n\nThe most striking update is probably that of 'aclocal'.\n\n'aclocal' now uses 'm4include' in the produced 'aclocal.m4' when\nthe included macros are already distributed with the package (an\nidiom used in many packages), which reduces code duplication. Many\npeople liked that, but in fact this change was really introduced to\nfix a bug in rebuild rules: 'Makefile.in' must be rebuilt whenever\na dependency of 'configure' changes, but all the 'm4' files\nincluded in 'aclocal.m4' where unknown from 'automake'. Now\n'automake' can just trace the 'm4include's to discover the\ndependencies.\n\n'aclocal' also starts using the '--trace' Autoconf option in order\nto discover used macros more accurately. This will turn out to be\nvery tricky (later releases will improve this) as people had\ndevised many ways to cope with the limitation of previous 'aclocal'\nversions, notably using handwritten 'm4include's: 'aclocal' must\nmake sure not to redefine a rule that is already included by such\nstatement.\n\nAutomake also has seen its guts rewritten. Although this rewriting\ntook a lot of efforts, it is only apparent to the users in that\nsome constructions previously disallowed by the implementation now\nwork nicely. Conditionals, Locations, Variable and Rule\ndefinitions, Options: these items on which Automake works have been\nrewritten as separate Perl modules, and documented.\n\n2004-01-11 Automake 1.8.1\n2004-01-12 Automake 1.8.2\n2004-03-07 Automake 1.8.3\n2004-04-25 Automake 1.8.4\n2004-05-16 Automake 1.8.5\n\n2004-07-28 Automake 1.9\n\nThis release tries to simplify the compilation rules it outputs to\nreduce the size of the Makefile. The complaint initially come from\nthe libgcj developers. Their 'Makefile.in' generated with Automake\n1.4 and custom build rules (1.4 did not support compiled Java) is\n250KB. The one generated by 1.8 was over 9MB! 1.9 gets it down to\n1.2MB.\n\nAside from this it contains mainly minor changes and bug-fixes.\n\n2004-08-11 Automake 1.9.1\n2004-09-19 Automake 1.9.2\n\nAutomake has ten years. This chapter of the manual was initially\nwritten for this occasion.\n\n2007-10-29 Automake repository moves to 'savannah.gnu.org'\nand uses git as primary repository.\n",
"subsections": []
},
"File: automake-history.info, Node: Dependency Tracking Evolution, Next: Releases, Prev: Timeline, Up: Top": {
"content": "",
"subsections": []
},
"2 Evolution of Automatic Dependency Tracking": {
"content": "",
"subsections": []
},
"Over the years Automake has deployed three different dependency tracking": {
"content": "methods. Each method, including the current one, has had flaws of\nvarious sorts. Here we lay out the different dependency tracking\nmethods, their flaws, and their fixes. We conclude with recommendations\nfor tool writers, and by indicating future directions for dependency\ntracking work in Automake.\n\n* Menu:\n\n* First Take on Dependencies:: Precomputed dependency tracking\n* Dependencies As Side Effects:: Update at developer compile time\n* Dependencies for the User:: Update at user compile time\n* Techniques for Dependencies:: Alternative approaches\n",
"subsections": []
},
"File: automake-history.info, Node: First Take on Dependencies, Next: Dependencies As Side Effects, Up: Dependency Tracking Evolution": {
"content": "",
"subsections": [
{
"name": "2.1 First Take on Dependency Tracking",
"content": ""
}
]
},
"Our first attempt at automatic dependency tracking was based on the": {
"content": "method recommended by GNU 'make'. (*note Generating Prerequisites",
"subsections": []
},
"Automatically: (make)Automatic Prerequisites.)": {
"content": "This version worked by precomputing dependencies ahead of time. For\neach source file, it had a special '.P' file that held the dependencies.",
"subsections": []
},
"There was a rule to generate a '.P' file by invoking the compiler": {
"content": "appropriately. All such '.P' files were included by the 'Makefile',\nthus implicitly becoming dependencies of 'Makefile'.\n\n\nThis approach had several critical bugs.\n\n* The code to generate the '.P' file relied on 'gcc'. (A limitation,\nnot technically a bug.)\n* The dependency tracking mechanism itself relied on GNU 'make'. (A\nlimitation, not technically a bug.)\n* Because each '.P' file was a dependency of 'Makefile', this meant\nthat dependency tracking was done eagerly by 'make'. For instance,\n'make clean' would cause all the dependency files to be updated,\nand then immediately removed. This eagerness also caused problems\nwith some configurations; if a certain source file could not be\ncompiled on a given architecture for some reason, dependency\ntracking would fail, aborting the entire build.\n* As dependency tracking was done as a pre-pass, compile times were\ndoubled-the compiler had to be run twice per source file.\n* 'make dist' re-ran 'automake' to generate a 'Makefile' that did not\nhave automatic dependency tracking (and that was thus portable to\nany version of 'make'). In order to do this portably, Automake had\nto scan the dependency files and remove any reference that was to a\nsource file not in the distribution. This process was error-prone.\nAlso, if 'make dist' was run in an environment where some object\nfile had a dependency on a source file that was only conditionally\ncreated, Automake would generate a 'Makefile' that referred to a\nfile that might not appear in the end user's build. A special,\nhacky mechanism was required to work around this.\n\n",
"subsections": []
},
"The code generated by Automake is often inspired by the 'Makefile' style": {
"content": "of a particular author. In the case of the first implementation of\ndependency tracking, I believe the impetus and inspiration was Jim",
"subsections": []
},
"Meyering. (I could be mistaken. If you know otherwise feel free to": {
"content": "correct me.)\n",
"subsections": []
},
"File: automake-history.info, Node: Dependencies As Side Effects, Next: Dependencies for the User, Prev: First Take on Dependencies, Up: Dependency Tracking Evolution": {
"content": "",
"subsections": [
{
"name": "2.2 Dependencies As Side Effects",
"content": ""
}
]
},
"The next refinement of Automake's automatic dependency tracking scheme": {
"content": "was to implement dependencies as side effects of the compilation. This\nwas aimed at solving the most commonly reported problems with the first\napproach. In particular we were most concerned with eliminating the\nweird rebuilding effect associated with make clean.\n\nIn this approach, the '.P' files were included using the '-include'\ncommand, which let us create these files lazily. This avoided the 'make\nclean' problem.\n\nWe only computed dependencies when a file was actually compiled.",
"subsections": []
},
"This avoided the performance penalty associated with scanning each file": {
"content": "twice. It also let us avoid the other problems associated with the\nfirst, eager, implementation. For instance, dependencies would never be\ngenerated for a source file that was not compilable on a given\narchitecture (because it in fact would never be compiled).\n\n\n* This approach also relied on the existence of 'gcc' and GNU 'make'.\n(A limitation, not technically a bug.)\n* Dependency tracking was still done by the developer, so the\nproblems from the first implementation relating to massaging of\ndependencies by 'make dist' were still in effect.\n* This implementation suffered from the \"deleted header file\"\nproblem. Suppose a lazily-created '.P' file includes a dependency\non a given header file, like this:\n\nmaude.o: maude.c something.h\n\nNow suppose that you remove 'something.h' and update 'maude.c' so\nthat this include is no longer needed. If you run 'make', you will\nget an error because there is no way to create 'something.h'.\n\nWe fixed this problem in a later release by further massaging the\noutput of 'gcc' to include a dummy dependency for each header file.\n",
"subsections": []
},
"File: automake-history.info, Node: Dependencies for the User, Next: Techniques for Dependencies, Prev: Dependencies As Side Effects, Up: Dependency Tracking Evolution": {
"content": "",
"subsections": [
{
"name": "2.3 Dependencies for the User",
"content": "The bugs associated with 'make dist', over time, became a real problem."
}
]
},
"Packages using Automake were being built on a large number of platforms,": {
"content": "and were becoming increasingly complex. Broken dependencies were\ndistributed in \"portable\" 'Makefile.in's, leading to user complaints.",
"subsections": []
},
"Also, the requirement for 'gcc' and GNU 'make' was a constant source of": {
"content": "bug reports. The next implementation of dependency tracking aimed to\nremove these problems.\n\nWe realized that the only truly reliable way to automatically track\ndependencies was to do it when the package itself was built. This meant\ndiscovering a method portable to any version of make and any compiler.",
"subsections": []
},
"Also, we wanted to preserve what we saw as the best point of the second": {
"content": "implementation: dependency computation as a side effect of compilation.\n\nIn the end we found that most modern make implementations support\nsome form of include directive. Also, we wrote a wrapper script that\nlet us abstract away differences between dependency tracking methods for\ncompilers. For instance, some compilers cannot generate dependencies as\na side effect of compilation. In this case we simply have the script\nrun the compiler twice. Currently our wrapper script ('depcomp') knows\nabout twelve different compilers (including a \"compiler\" that simply\ninvokes 'makedepend' and then the real compiler, which is assumed to be\na standard Unix-like C compiler with no way to do dependency tracking).\n\n\n* Running a wrapper script for each compilation slows down the build.\n* Many users don't really care about precise dependencies.\n* This implementation, like every other automatic dependency tracking\nscheme in common use today (indeed, every one we've ever heard of),\nsuffers from the \"duplicated new header\" bug.\n\nThis bug occurs because dependency tracking tools, such as the\ncompiler, only generate dependencies on the successful opening of a\nfile, and not on every probe.\n\nSuppose for instance that the compiler searches three directories\nfor a given header, and that the header is found in the third\ndirectory. If the programmer erroneously adds a header file with\nthe same name to the first directory, then a clean rebuild from\nscratch could fail (suppose the new header file is buggy), whereas\nan incremental rebuild will succeed.\n\nWhat has happened here is that people have a misunderstanding of\nwhat a dependency is. Tool writers think a dependency encodes\ninformation about which files were read by the compiler. However,\na dependency must actually encode information about what the\ncompiler tried to do.\n\nThis problem is not serious in practice. Programmers typically do\nnot use the same name for a header file twice in a given project.\n(At least, not in C or C++. This problem may be more troublesome\nin Java.) This problem is easy to fix, by modifying dependency\ngenerators to record every probe, instead of every successful open.\n\n* Since Automake generates dependencies as a side effect of\ncompilation, there is a bootstrapping problem when header files are\ngenerated by running a program. The problem is that, the first\ntime the build is done, there is no way by default to know that the\nheaders are required, so make might try to run a compilation for\nwhich the headers have not yet been built.\n\nThis was also a problem in the previous dependency tracking\nimplementation.\n\nThe current fix is to use 'BUILTSOURCES' to list built headers\n(*note Sources: (automake)Sources.). This causes them to be built\nbefore any other build rules are run. This is unsatisfactory as a\ngeneral solution, however in practice it seems sufficient for most\nactual programs.\n\nThis code is used since Automake 1.5.\n\nIn GCC 3.0, we managed to convince the maintainers to add special\ncommand-line options to help Automake more efficiently do its job. We\nhoped this would let us avoid the use of a wrapper script when\nAutomake's automatic dependency tracking was used with 'gcc'.\n\nUnfortunately, this code doesn't quite do what we want. In\nparticular, it removes the dependency file if the compilation fails;\nwe'd prefer that it instead only touch the file in any way if the\ncompilation succeeds.\n\nNevertheless, since Automake 1.7, when a recent 'gcc' is detected at\n'configure' time, we inline the dependency-generation code and do not\nuse the 'depcomp' wrapper script. This makes compilations faster for\nthose using this compiler (probably our primary user base). The\ncounterpart is that because we have to encode two compilation rules in\n'Makefile' (with or without 'depcomp'), the produced 'Makefile's are\nlarger.\n",
"subsections": []
},
"File: automake-history.info, Node: Techniques for Dependencies, Prev: Dependencies for the User, Up: Dependency Tracking Evolution": {
"content": "",
"subsections": [
{
"name": "2.4 Techniques for Computing Dependencies",
"content": ""
}
]
},
"There are actually several ways for a build tool like Automake to cause": {
"content": "tools to generate dependencies.\n\n'makedepend'\nThis was a commonly-used method in the past. The idea is to run a\nspecial program over the source and have it generate dependency\ninformation. Traditional implementations of 'makedepend' are not\ncompletely precise; ordinarily they were conservative and\ndiscovered too many dependencies.\nThe tool\nAn obvious way to generate dependencies is to simply write the tool\nso that it can generate the information needed by the build tool.\nThis is also the most portable method. Many compilers have an\noption to generate dependencies. Unfortunately, not all tools\nprovide such an option.\nThe file system\nIt is possible to write a special file system that tracks opens,\nreads, writes, etc, and then feed this information back to the\nbuild tool. 'clearmake' does this. This is a very powerful\ntechnique, as it doesn't require cooperation from the tool.\nUnfortunately it is also very difficult to implement and also not\npractical in the general case.\n'LDPRELOAD'\nRather than use the file system, one could write a special library\nto intercept 'open' and other syscalls. This technique is also\nquite powerful, but unfortunately it is not portable enough for use\nin 'automake'.\n\n* Menu:\n\n* Recommendations for Tool Writers::\n* Future Directions for Dependencies::\n",
"subsections": []
},
"File: automake-history.info, Node: Recommendations for Tool Writers, Next: Future Directions for Dependencies, Up: Techniques for Dependencies": {
"content": "",
"subsections": []
},
"We think that every compilation tool ought to be able to generate": {
"content": "dependencies as a side effect of compilation. Furthermore, at least\nwhile 'make'-based tools are nearly universally in use (at least in the\nfree software community), the tool itself should generate dummy\ndependencies for header files, to avoid the deleted header file bug.",
"subsections": []
},
"Finally, the tool should generate a dependency for each probe, instead": {
"content": "of each successful file open, in order to avoid the duplicated new\nheader bug.\n",
"subsections": []
},
"File: automake-history.info, Node: Future Directions for Dependencies, Prev: Recommendations for Tool Writers, Up: Techniques for Dependencies": {
"content": "",
"subsections": []
},
"Currently, only languages and compilers understood by Automake can have": {
"content": "dependency tracking enabled. We would like to see if it is practical\n(and worthwhile) to let this support be extended by the user to\nlanguages unknown to Automake.\n",
"subsections": []
},
"File: automake-history.info, Node: Releases, Next: Copying This Manual, Prev: Dependency Tracking Evolution, Up: Top": {
"content": "",
"subsections": []
},
"3 Release Statistics": {
"content": "",
"subsections": []
},
"The following table (inspired by 'perlhist(1)') quantifies the evolution": {
"content": "of Automake using these metrics:\n\nDate, Rel\nThe date and version of the release.\nam\nThe number of lines of the 'automake' script.\nacl\nThe number of lines of the 'aclocal' script.\npm\nThe number of lines of the 'Perl' supporting modules.\n'*.am'\nThe number of lines of the 'Makefile' fragments. The number in\nparentheses is the number of files.\nm4\nThe number of lines (and files) of Autoconf macros.\ndoc\nThe number of pages of the documentation (the Postscript version).\nt\nThe number of test cases in the test suite. Of those, the number\nin parentheses is the number of generated test cases.\n\n1994-09-19 CVS 141 299 (24)\n1994-11-05 CVS 208 332 (28)\n1995-11-23 0.20 533 458 (35) 9\n1995-11-26 0.21 613 480 (36) 11\n1995-11-28 0.22 1116 539 (38) 12\n1995-11-29 0.23 1240 541 (38) 12\n1995-12-08 0.24 1462 504 (33) 14\n1995-12-10 0.25 1513 511 (37) 15\n1996-01-03 0.26 1706 438 (36) 16\n1996-01-03 0.27 1706 438 (36) 16\n1996-01-13 0.28 1964 934 (33) 16\n1996-02-07 0.29 2299 936 (33) 17\n1996-02-24 0.30 2544 919 (32) 85 (1) 20 9\n1996-03-11 0.31 2877 919 (32) 85 (1) 29 17\n1996-04-27 0.32 3058 921 (31) 85 (1) 30 26\n1996-05-18 0.33 3110 926 (31) 105 (1) 30 35\n1996-05-28 1.0 3134 973 (32) 105 (1) 30 38\n1997-06-22 1.2 6089 385 1294 (36) 592 (20) 37 126\n1998-04-05 1.3 6415 422 1470 (39) 741 (23) 39 156\n1999-01-14 1.4 7240 426 1591 (40) 734 (20) 51 197\n2001-05-08 1.4-p1 7251 426 1591 (40) 734 (20) 51 197\n2001-05-24 1.4-p2 7268 439 1591 (40) 734 (20) 49 197\n2001-06-07 1.4-p3 7312 439 1591 (40) 734 (20) 49 197\n2001-06-10 1.4-p4 7321 439 1591 (40) 734 (20) 49 198\n2001-07-15 1.4-p5 7228 426 1596 (40) 734 (20) 51 198\n2001-08-23 1.5 8016 475 600 2654 (39) 1166 (29) 63 327\n2002-03-05 1.6 8465 475 1136 2732 (39) 1603 (27) 66 365\n2002-04-11 1.6.1 8544 475 1136 2741 (39) 1603 (27) 66 372\n2002-06-14 1.6.2 8575 475 1136 2800 (39) 1609 (27) 67 386\n2002-07-28 1.6.3 8600 475 1153 2809 (39) 1609 (27) 67 391\n2002-07-28 1.4-p6 7332 455 1596 (40) 735 (20) 49 197\n2002-09-25 1.7 9189 471 1790 2965 (39) 1606 (28) 73 430\n2002-10-16 1.7.1 9229 475 1790 2977 (39) 1606 (28) 73 437\n2002-12-06 1.7.2 9334 475 1790 2988 (39) 1606 (28) 77 445\n2003-02-20 1.7.3 9389 475 1790 3023 (39) 1651 (29) 84 448\n2003-04-23 1.7.4 9429 475 1790 3031 (39) 1644 (29) 85 458\n2003-05-18 1.7.5 9429 475 1790 3033 (39) 1645 (29) 85 459\n2003-07-10 1.7.6 9442 475 1790 3033 (39) 1660 (29) 85 461\n2003-09-07 1.7.7 9443 475 1790 3041 (39) 1660 (29) 90 467\n2003-10-07 1.7.8 9444 475 1790 3041 (39) 1660 (29) 90 468\n2003-11-09 1.7.9 9444 475 1790 3048 (39) 1660 (29) 90 468\n2003-12-10 1.8 7171 585 7730 3236 (39) 1666 (31) 104 521\n2004-01-11 1.8.1 7217 663 7726 3287 (39) 1686 (31) 104 525\n2004-01-12 1.8.2 7217 663 7726 3288 (39) 1686 (31) 104 526\n2004-03-07 1.8.3 7214 686 7735 3303 (39) 1695 (31) 111 530\n2004-04-25 1.8.4 7214 686 7736 3310 (39) 1701 (31) 112 531\n2004-05-16 1.8.5 7240 686 7736 3299 (39) 1701 (31) 112 533\n2004-07-28 1.9 7508 715 7794 3352 (40) 1812 (32) 115 551\n2004-08-11 1.9.1 7512 715 7794 3354 (40) 1812 (32) 115 552\n2004-09-19 1.9.2 7512 715 7794 3354 (40) 1812 (32) 132 554\n2004-11-01 1.9.3 7507 718 7804 3354 (40) 1812 (32) 134 556\n2004-12-18 1.9.4 7508 718 7856 3361 (40) 1811 (32) 140 560\n2005-02-13 1.9.5 7523 719 7859 3373 (40) 1453 (32) 142 562\n2005-07-10 1.9.6 7539 699 7867 3400 (40) 1453 (32) 144 570\n2006-10-15 1.10 7859 1072 8024 3512 (40) 1496 (34) 172 604\n2008-01-19 1.10.1 7870 1089 8025 3520 (40) 1499 (34) 173 617\n2008-11-23 1.10.2 7882 1089 8027 3540 (40) 1509 (34) 176 628\n2009-05-17 1.11 8721 1092 8289 4164 (42) 1714 (37) 181 732 (20)\n",
"subsections": []
},
"File: automake-history.info, Node: Copying This Manual, Prev: Releases, Up: Top": {
"content": "",
"subsections": []
},
"Appendix A Copying This Manual": {
"content": "* Menu:\n\n* GNU Free Documentation License:: License for copying this manual\n",
"subsections": []
},
"File: automake-history.info, Node: GNU Free Documentation License, Up: Copying This Manual": {
"content": "",
"subsections": [
{
"name": "A.1 GNU Free Documentation License",
"content": "Version 1.3, 3 November 2008\n\nCopyright (C) 2000-2021 Free Software Foundation, Inc.\n\n\nEveryone is permitted to copy and distribute verbatim copies\nof this license document, but changing it is not allowed.\n\n0. PREAMBLE\n\nThe purpose of this License is to make a manual, textbook, or other\nfunctional and useful document \"free\" in the sense of freedom: to\nassure everyone the effective freedom to copy and redistribute it,\nwith or without modifying it, either commercially or\nnoncommercially. Secondarily, this License preserves for the\nauthor and publisher a way to get credit for their work, while not\nbeing considered responsible for modifications made by others.\n\nThis License is a kind of \"copyleft\", which means that derivative\nworks of the document must themselves be free in the same sense.\nIt complements the GNU General Public License, which is a copyleft\nlicense designed for free software.\n\nWe have designed this License in order to use it for manuals for\nfree software, because free software needs free documentation: a\nfree program should come with manuals providing the same freedoms\nthat the software does. But this License is not limited to\nsoftware manuals; it can be used for any textual work, regardless\nof subject matter or whether it is published as a printed book. We\nrecommend this License principally for works whose purpose is\ninstruction or reference.\n\n1. APPLICABILITY AND DEFINITIONS\n\nThis License applies to any manual or other work, in any medium,\nthat contains a notice placed by the copyright holder saying it can\nbe distributed under the terms of this License. Such a notice\ngrants a world-wide, royalty-free license, unlimited in duration,\nto use that work under the conditions stated herein. The\n\"Document\", below, refers to any such manual or work. Any member\nof the public is a licensee, and is addressed as \"you\". You accept\nthe license if you copy, modify or distribute the work in a way\nrequiring permission under copyright law.\n\nA \"Modified Version\" of the Document means any work containing the\nDocument or a portion of it, either copied verbatim, or with\nmodifications and/or translated into another language.\n\nA \"Secondary Section\" is a named appendix or a front-matter section\nof the Document that deals exclusively with the relationship of the\npublishers or authors of the Document to the Document's overall\nsubject (or to related matters) and contains nothing that could\nfall directly within that overall subject. (Thus, if the Document\nis in part a textbook of mathematics, a Secondary Section may not\nexplain any mathematics.) The relationship could be a matter of\nhistorical connection with the subject or with related matters, or\nof legal, commercial, philosophical, ethical or political position\nregarding them.\n\nThe \"Invariant Sections\" are certain Secondary Sections whose\ntitles are designated, as being those of Invariant Sections, in the\nnotice that says that the Document is released under this License.\nIf a section does not fit the above definition of Secondary then it\nis not allowed to be designated as Invariant. The Document may\ncontain zero Invariant Sections. If the Document does not identify\nany Invariant Sections then there are none.\n\nThe \"Cover Texts\" are certain short passages of text that are\nlisted, as Front-Cover Texts or Back-Cover Texts, in the notice\nthat says that the Document is released under this License. A\nFront-Cover Text may be at most 5 words, and a Back-Cover Text may\nbe at most 25 words.\n\nA \"Transparent\" copy of the Document means a machine-readable copy,\nrepresented in a format whose specification is available to the\ngeneral public, that is suitable for revising the document\nstraightforwardly with generic text editors or (for images composed\nof pixels) generic paint programs or (for drawings) some widely\navailable drawing editor, and that is suitable for input to text\nformatters or for automatic translation to a variety of formats\nsuitable for input to text formatters. A copy made in an otherwise\nTransparent file format whose markup, or absence of markup, has\nbeen arranged to thwart or discourage subsequent modification by\nreaders is not Transparent. An image format is not Transparent if\nused for any substantial amount of text. A copy that is not\n\"Transparent\" is called \"Opaque\".\n\nExamples of suitable formats for Transparent copies include plain\nASCII without markup, Texinfo input format, LaTeX input format,\nSGML or XML using a publicly available DTD, and standard-conforming\nsimple HTML, PostScript or PDF designed for human modification.\nExamples of transparent image formats include PNG, XCF and JPG.\nOpaque formats include proprietary formats that can be read and\nedited only by proprietary word processors, SGML or XML for which\nthe DTD and/or processing tools are not generally available, and\nthe machine-generated HTML, PostScript or PDF produced by some word\nprocessors for output purposes only.\n\nThe \"Title Page\" means, for a printed book, the title page itself,\nplus such following pages as are needed to hold, legibly, the\nmaterial this License requires to appear in the title page. For\nworks in formats which do not have any title page as such, \"Title\nPage\" means the text near the most prominent appearance of the\nwork's title, preceding the beginning of the body of the text.\n\nThe \"publisher\" means any person or entity that distributes copies\nof the Document to the public.\n\nA section \"Entitled XYZ\" means a named subunit of the Document\nwhose title either is precisely XYZ or contains XYZ in parentheses\nfollowing text that translates XYZ in another language. (Here XYZ\nstands for a specific section name mentioned below, such as\n\"Acknowledgements\", \"Dedications\", \"Endorsements\", or \"History\".)\nTo \"Preserve the Title\" of such a section when you modify the\nDocument means that it remains a section \"Entitled XYZ\" according\nto this definition.\n\nThe Document may include Warranty Disclaimers next to the notice\nwhich states that this License applies to the Document. These\nWarranty Disclaimers are considered to be included by reference in\nthis License, but only as regards disclaiming warranties: any other\nimplication that these Warranty Disclaimers may have is void and\nhas no effect on the meaning of this License.\n\n2. VERBATIM COPYING\n\nYou may copy and distribute the Document in any medium, either\ncommercially or noncommercially, provided that this License, the\ncopyright notices, and the license notice saying this License\napplies to the Document are reproduced in all copies, and that you\nadd no other conditions whatsoever to those of this License. You\nmay not use technical measures to obstruct or control the reading\nor further copying of the copies you make or distribute. However,\nyou may accept compensation in exchange for copies. If you\ndistribute a large enough number of copies you must also follow the\nconditions in section 3.\n\nYou may also lend copies, under the same conditions stated above,\nand you may publicly display copies.\n\n3. COPYING IN QUANTITY\n\nIf you publish printed copies (or copies in media that commonly\nhave printed covers) of the Document, numbering more than 100, and\nthe Document's license notice requires Cover Texts, you must\nenclose the copies in covers that carry, clearly and legibly, all\nthese Cover Texts: Front-Cover Texts on the front cover, and\nBack-Cover Texts on the back cover. Both covers must also clearly\nand legibly identify you as the publisher of these copies. The\nfront cover must present the full title with all words of the title\nequally prominent and visible. You may add other material on the\ncovers in addition. Copying with changes limited to the covers, as\nlong as they preserve the title of the Document and satisfy these\nconditions, can be treated as verbatim copying in other respects.\n\nIf the required texts for either cover are too voluminous to fit\nlegibly, you should put the first ones listed (as many as fit\nreasonably) on the actual cover, and continue the rest onto\nadjacent pages.\n\nIf you publish or distribute Opaque copies of the Document\nnumbering more than 100, you must either include a machine-readable\nTransparent copy along with each Opaque copy, or state in or with\neach Opaque copy a computer-network location from which the general\nnetwork-using public has access to download using public-standard\nnetwork protocols a complete Transparent copy of the Document, free\nof added material. If you use the latter option, you must take\nreasonably prudent steps, when you begin distribution of Opaque\ncopies in quantity, to ensure that this Transparent copy will\nremain thus accessible at the stated location until at least one\nyear after the last time you distribute an Opaque copy (directly or\nthrough your agents or retailers) of that edition to the public.\n\nIt is requested, but not required, that you contact the authors of\nthe Document well before redistributing any large number of copies,\nto give them a chance to provide you with an updated version of the\nDocument.\n\n4. MODIFICATIONS\n\nYou may copy and distribute a Modified Version of the Document\nunder the conditions of sections 2 and 3 above, provided that you\nrelease the Modified Version under precisely this License, with the\nModified Version filling the role of the Document, thus licensing\ndistribution and modification of the Modified Version to whoever\npossesses a copy of it. In addition, you must do these things in\nthe Modified Version:\n\nA. Use in the Title Page (and on the covers, if any) a title\ndistinct from that of the Document, and from those of previous\nversions (which should, if there were any, be listed in the\nHistory section of the Document). You may use the same title\nas a previous version if the original publisher of that\nversion gives permission.\n\nB. List on the Title Page, as authors, one or more persons or\nentities responsible for authorship of the modifications in\nthe Modified Version, together with at least five of the\nprincipal authors of the Document (all of its principal\nauthors, if it has fewer than five), unless they release you\nfrom this requirement.\n\nC. State on the Title page the name of the publisher of the\nModified Version, as the publisher.\n\nD. Preserve all the copyright notices of the Document.\n\nE. Add an appropriate copyright notice for your modifications\nadjacent to the other copyright notices.\n\nF. Include, immediately after the copyright notices, a license\nnotice giving the public permission to use the Modified\nVersion under the terms of this License, in the form shown in\nthe Addendum below.\n\nG. Preserve in that license notice the full lists of Invariant\nSections and required Cover Texts given in the Document's\nlicense notice.\n\nH. Include an unaltered copy of this License.\n\nI. Preserve the section Entitled \"History\", Preserve its Title,\nand add to it an item stating at least the title, year, new\nauthors, and publisher of the Modified Version as given on the\nTitle Page. If there is no section Entitled \"History\" in the\nDocument, create one stating the title, year, authors, and\npublisher of the Document as given on its Title Page, then add\nan item describing the Modified Version as stated in the\nprevious sentence.\n\nJ. Preserve the network location, if any, given in the Document\nfor public access to a Transparent copy of the Document, and\nlikewise the network locations given in the Document for\nprevious versions it was based on. These may be placed in the\n\"History\" section. You may omit a network location for a work\nthat was published at least four years before the Document\nitself, or if the original publisher of the version it refers\nto gives permission.\n\nK. For any section Entitled \"Acknowledgements\" or \"Dedications\",\nPreserve the Title of the section, and preserve in the section\nall the substance and tone of each of the contributor\nacknowledgements and/or dedications given therein.\n\nL. Preserve all the Invariant Sections of the Document, unaltered\nin their text and in their titles. Section numbers or the\nequivalent are not considered part of the section titles.\n\nM. Delete any section Entitled \"Endorsements\". Such a section\nmay not be included in the Modified Version.\n\nN. Do not retitle any existing section to be Entitled\n\"Endorsements\" or to conflict in title with any Invariant\nSection.\n\nO. Preserve any Warranty Disclaimers.\n\nIf the Modified Version includes new front-matter sections or\nappendices that qualify as Secondary Sections and contain no\nmaterial copied from the Document, you may at your option designate\nsome or all of these sections as invariant. To do this, add their\ntitles to the list of Invariant Sections in the Modified Version's\nlicense notice. These titles must be distinct from any other\nsection titles.\n\nYou may add a section Entitled \"Endorsements\", provided it contains\nnothing but endorsements of your Modified Version by various\nparties--for example, statements of peer review or that the text\nhas been approved by an organization as the authoritative\ndefinition of a standard.\n\nYou may add a passage of up to five words as a Front-Cover Text,\nand a passage of up to 25 words as a Back-Cover Text, to the end of\nthe list of Cover Texts in the Modified Version. Only one passage\nof Front-Cover Text and one of Back-Cover Text may be added by (or\nthrough arrangements made by) any one entity. If the Document\nalready includes a cover text for the same cover, previously added\nby you or by arrangement made by the same entity you are acting on\nbehalf of, you may not add another; but you may replace the old\none, on explicit permission from the previous publisher that added\nthe old one.\n\nThe author(s) and publisher(s) of the Document do not by this\nLicense give permission to use their names for publicity for or to\nassert or imply endorsement of any Modified Version.\n\n5. COMBINING DOCUMENTS\n\nYou may combine the Document with other documents released under\nthis License, under the terms defined in section 4 above for\nmodified versions, provided that you include in the combination all\nof the Invariant Sections of all of the original documents,\nunmodified, and list them all as Invariant Sections of your\ncombined work in its license notice, and that you preserve all\ntheir Warranty Disclaimers.\n\nThe combined work need only contain one copy of this License, and\nmultiple identical Invariant Sections may be replaced with a single\ncopy. If there are multiple Invariant Sections with the same name\nbut different contents, make the title of each such section unique\nby adding at the end of it, in parentheses, the name of the\noriginal author or publisher of that section if known, or else a\nunique number. Make the same adjustment to the section titles in\nthe list of Invariant Sections in the license notice of the\ncombined work.\n\nIn the combination, you must combine any sections Entitled\n\"History\" in the various original documents, forming one section\nEntitled \"History\"; likewise combine any sections Entitled\n\"Acknowledgements\", and any sections Entitled \"Dedications\". You\nmust delete all sections Entitled \"Endorsements.\"\n\n6. COLLECTIONS OF DOCUMENTS\n\nYou may make a collection consisting of the Document and other\ndocuments released under this License, and replace the individual\ncopies of this License in the various documents with a single copy\nthat is included in the collection, provided that you follow the\nrules of this License for verbatim copying of each of the documents\nin all other respects.\n\nYou may extract a single document from such a collection, and\ndistribute it individually under this License, provided you insert\na copy of this License into the extracted document, and follow this\nLicense in all other respects regarding verbatim copying of that\ndocument.\n\n7. AGGREGATION WITH INDEPENDENT WORKS\n\nA compilation of the Document or its derivatives with other\nseparate and independent documents or works, in or on a volume of a\nstorage or distribution medium, is called an \"aggregate\" if the\ncopyright resulting from the compilation is not used to limit the\nlegal rights of the compilation's users beyond what the individual\nworks permit. When the Document is included in an aggregate, this\nLicense does not apply to the other works in the aggregate which\nare not themselves derivative works of the Document.\n\nIf the Cover Text requirement of section 3 is applicable to these\ncopies of the Document, then if the Document is less than one half\nof the entire aggregate, the Document's Cover Texts may be placed\non covers that bracket the Document within the aggregate, or the\nelectronic equivalent of covers if the Document is in electronic\nform. Otherwise they must appear on printed covers that bracket\nthe whole aggregate.\n\n8. TRANSLATION\n\nTranslation is considered a kind of modification, so you may\ndistribute translations of the Document under the terms of section\n4. Replacing Invariant Sections with translations requires special\npermission from their copyright holders, but you may include\ntranslations of some or all Invariant Sections in addition to the\noriginal versions of these Invariant Sections. You may include a\ntranslation of this License, and all the license notices in the\nDocument, and any Warranty Disclaimers, provided that you also\ninclude the original English version of this License and the\noriginal versions of those notices and disclaimers. In case of a\ndisagreement between the translation and the original version of\nthis License or a notice or disclaimer, the original version will\nprevail.\n\nIf a section in the Document is Entitled \"Acknowledgements\",\n\"Dedications\", or \"History\", the requirement (section 4) to\nPreserve its Title (section 1) will typically require changing the\nactual title.\n\n9. TERMINATION\n\nYou may not copy, modify, sublicense, or distribute the Document\nexcept as expressly provided under this License. Any attempt\notherwise to copy, modify, sublicense, or distribute it is void,\nand will automatically terminate your rights under this License.\n\nHowever, if you cease all violation of this License, then your\nlicense from a particular copyright holder is reinstated (a)\nprovisionally, unless and until the copyright holder explicitly and\nfinally terminates your license, and (b) permanently, if the\ncopyright holder fails to notify you of the violation by some\nreasonable means prior to 60 days after the cessation.\n\nMoreover, your license from a particular copyright holder is\nreinstated permanently if the copyright holder notifies you of the\nviolation by some reasonable means, this is the first time you have\nreceived notice of violation of this License (for any work) from\nthat copyright holder, and you cure the violation prior to 30 days\nafter your receipt of the notice.\n\nTermination of your rights under this section does not terminate\nthe licenses of parties who have received copies or rights from you\nunder this License. If your rights have been terminated and not\npermanently reinstated, receipt of a copy of some or all of the\nsame material does not give you any rights to use it.\n\n10. FUTURE REVISIONS OF THIS LICENSE\n\nThe Free Software Foundation may publish new, revised versions of\nthe GNU Free Documentation License from time to time. Such new\nversions will be similar in spirit to the present version, but may\ndiffer in detail to address new problems or concerns. See\n.\n\nEach version of the License is given a distinguishing version\nnumber. If the Document specifies that a particular numbered\nversion of this License \"or any later version\" applies to it, you\nhave the option of following the terms and conditions either of\nthat specified version or of any later version that has been\npublished (not as a draft) by the Free Software Foundation. If the\nDocument does not specify a version number of this License, you may\nchoose any version ever published (not as a draft) by the Free\nSoftware Foundation. If the Document specifies that a proxy can\ndecide which future versions of this License can be used, that\nproxy's public statement of acceptance of a version permanently\nauthorizes you to choose that version for the Document.\n\n11. RELICENSING\n\n\"Massive Multiauthor Collaboration Site\" (or \"MMC Site\") means any\nWorld Wide Web server that publishes copyrightable works and also\nprovides prominent facilities for anybody to edit those works. A\npublic wiki that anybody can edit is an example of such a server.\nA \"Massive Multiauthor Collaboration\" (or \"MMC\") contained in the\nsite means any set of copyrightable works thus published on the MMC\nsite.\n\n\"CC-BY-SA\" means the Creative Commons Attribution-Share Alike 3.0\nlicense published by Creative Commons Corporation, a not-for-profit\ncorporation with a principal place of business in San Francisco,\nCalifornia, as well as future copyleft versions of that license\npublished by that same organization.\n\n\"Incorporate\" means to publish or republish a Document, in whole or\nin part, as part of another Document.\n\nAn MMC is \"eligible for relicensing\" if it is licensed under this\nLicense, and if all works that were first published under this\nLicense somewhere other than this MMC, and subsequently\nincorporated in whole or in part into the MMC, (1) had no cover\ntexts or invariant sections, and (2) were thus incorporated prior\nto November 1, 2008.\n\nThe operator of an MMC Site may republish an MMC contained in the\nsite under CC-BY-SA on the same site at any time before August 1,\n2009, provided the MMC is eligible for relicensing.\n"
},
{
"name": "ADDENDUM: How to use this License for your documents",
"content": ""
}
]
},
"To use this License in a document you have written, include a copy of": {
"content": "the License in the document and put the following copyright and license\nnotices just after the title page:\n\nCopyright (C) YEAR YOUR NAME.\nPermission is granted to copy, distribute and/or modify this document\nunder the terms of the GNU Free Documentation License, Version 1.3\nor any later version published by the Free Software Foundation;\nwith no Invariant Sections, no Front-Cover Texts, and no Back-Cover\nTexts. A copy of the license is included in the section entitled ``GNU\nFree Documentation License''.\n\nIf you have Invariant Sections, Front-Cover Texts and Back-Cover\nTexts, replace the \"with...Texts.\" line with this:\n\nwith the Invariant Sections being LIST THEIR TITLES, with\nthe Front-Cover Texts being LIST, and with the Back-Cover Texts\nbeing LIST.\n\nIf you have Invariant Sections without Cover Texts, or some other\ncombination of the three, merge those two alternatives to suit the\nsituation.\n\nIf your document contains nontrivial examples of program code, we\nrecommend releasing these examples in parallel under your choice of free\nsoftware license, such as the GNU General Public License, to permit\ntheir use in free software.\n\n",
"subsections": []
}
},
"flags": [],
"examples": [],
"see_also": []
}