https://svn.lrde.epita.fr/svn/lrde-tools/trunk ChangeLog | 5 ++ README | 3 + doc/lrdetools.texi | 104 +++++++++++++++++++++++++++++++++++++++++++++++------ 3 files changed, 102 insertions(+), 10 deletions(-) Index: ChangeLog from Akim Demaille <akim(a)epita.fr> * src/symbuild: New. * doc/lrdetools.texi (symbuild): New. Index: README --- README (revision 119) +++ README (working copy) @@ -105,6 +105,9 @@ ** rdiff Recursive diff between two files/tarballs. +** symbuild +Easy navigation between source and build trees + ** tarr Quickly make tarballs. Index: doc/lrdetools.texi --- doc/lrdetools.texi (revision 119) +++ doc/lrdetools.texi (working copy) @@ -132,17 +132,18 @@ Miscellaneous utilities * apatche:: Send patches to a mailing list -* checkin:: Update ChangeLog, do a checkin and post a news. +* checkin:: Update ChangeLog, do a checkin and post a news * cl2patch:: Prepare a patch for application * diffed:: Manipulate patches in the diff format * g2b:: Gzip to Bzip2 * insist:: Repeatedly do something until it succeeds * install-on:: Install a package on a remote machine. -* rdiff:: Recursive diff between two files/tarballs. +* rdiff:: Recursive diff between two files/tarballs +* symbuild:: Easy navigation between source and build trees * tarr:: Quickly make tarballs. -* timeout:: Run a command and killing it if it is too slow. -* whitespace:: Normalize whitespace uses in files. -* xdiff:: A btter interface to diff +* timeout:: Run a command and killing it if it is too slow +* whitespace:: Normalize whitespace uses in files +* xdiff:: A better interface to diff @command{checkin} @@ -310,17 +311,18 @@ @menu * apatche:: Send patches to a mailing list -* checkin:: Update ChangeLog, do a checkin and post a news. +* checkin:: Update ChangeLog, do a checkin and post a news * cl2patch:: Prepare a patch for application * diffed:: Manipulate patches in the diff format * g2b:: Gzip to Bzip2 * insist:: Repeatedly do something until it succeeds * install-on:: Install a package on a remote machine. -* rdiff:: Recursive diff between two files/tarballs. +* rdiff:: Recursive diff between two files/tarballs +* symbuild:: Easy navigation between source and build trees * tarr:: Quickly make tarballs. -* timeout:: Run a command and killing it if it is too slow. -* whitespace:: Normalize whitespace uses in files. -* xdiff:: A btter interface to diff +* timeout:: Run a command and killing it if it is too slow +* whitespace:: Normalize whitespace uses in files +* xdiff:: A better interface to diff @end menu @node apatche @@ -500,6 +502,88 @@ @section @command{rdiff} Recursive diff between two files/tarballs. +@node symbuild +@section @command{symbuild} + +Create a set of crossed source/build symbolic links. + +For many reasons, it is recommended to build in a different directory +than where the sources are. This is named ``VPATH-build'' in the +Automake documentation, and it is often referred to as ``build != src +build''. Projects using the Autotools naturally support this set up, +instead of: + +@example +$ @kbd{tar zxvf foo-1.0.tar.gz} +$ @kbd{cd foo-1.0} +$ @kbd{./configure} +$ @kbd{make} +$ @kbd{make check} +$ @kbd{make install} +@end example + +@noindent +run + +@example +$ @kbd{tar zxvf foo-1.0.tar.gz} +$ @kbd{cd foo-1.0} +$ @kbd{mkdir _build} +$ @kbd{cd _build} +$ @kbd{../configure} +$ @kbd{make} +$ @kbd{make check} +$ @kbd{make install} +@end example + +This set up has several drawbacks: +@table @asis +@item compiling under Emacs +If you have a deep package and you are currently editing +(a)file{src/parse/parsetiger.yy}, then you have to compile using +@samp{make -C ../../_build/src/parse}. In non-VPATH builds, a simple +@samp{make} suffices! + +@item exploring directories +Sometimes you check some output files in the build hierarchy, say +(a)file{scantiger.cc} in @file{_build/src/parse}. But now you want to see +the source file: @file{../../../src/parse/scantiger.ll}. Of course in +non-VPATH build there are no such problems. +@end table + +@command{symbuild} attempts to recover the easy navigation provided by +installing symbolic links between peer source/build directories. For +instance, @file{src/parse} contains a @file{_build} symbolic link that +points to @file{../../_build/src/parse}. And @file{_build/src/parse} +contains a @file{_src} symlink pointing to @file{../../../src/parse}. + +Usage: + +@example + symbuild +or symbuild @var{builddir} +@end example + +@noindent +where @var{builddir} is the name of the top level build directory, +defaulting to @file{_build}. Run this script from the source top level: +the @var{builddir} must exist. For instance: + +@example +$ @kbd{tar zxvf foo-1.0.tar.gz} +$ @kbd{cd foo-1.0} +$ @kbd{mkdir _build} +$ @kbd{symbuild} +$ @kbd{cd _build} +$ @kbd{../configure} +$ @kbd{make} +$ @kbd{make check} +$ @kbd{make install} +@end example + +@noindent +and then enjoy a simple and constant @samp{make -C _build} under Emacs! + @node tarr @section @command{tarr} Quickly make tarballs.