$Id: AutoMake-guide,v 1.10 2003/03/24 08:26:28 ddurham Exp $ AutoMake-guide Anthony Ventimiglia This is meant to be a rough guide to adding files in the ReZound source directory and build process. It would be a help to all the package maintainers if everyone works to keep the build process complete and the dependencies accurate. If you are already experienced with using gnu autotools, and writing Makefile.am's for use with automake, please read this anyway, and try to follow the style I've used. Who knows, you might learn something or get some new ideas, or you might totally hate the way I've done things and have a better way of doing it. Feel free to send us any ideas, suggestions, comments or questions you may have. Every source directory, starting from the top level, has it's own Makefile.am which is responsible for compiling the files in it's directory. automake converts Makefile.am into Makefile.in which is converted to a Makefile using the results on configure. Here is a visual layout of the overall build process, basically it's what happens when you type make at the top level directory. TOP_DIRECTORY/make | |- src/make | misc/make--| | |misc/cc++/make --- libmisc.la | | | |misc/CNestedDataFile/make --- libmiscCN.la | PoolFile/make -- libPoolFile.la | backend/make--| | backend/DSP/make | | | backend/Edits/make -- libEdits.la | | | backend/Effects/make -- libEffects.la | | | backend/Filters/make -- libFilters.la | | | backend/Looping/make -- libLooping.la | | | backend/Remaster/make -- libRemaster.la | |------ libbackend.la | frontend_fox/make --- libfrontend_fox.la | |-link libmisc.la --------| libPoolFile.la --------| libEdits.la --------| libEffects.la --------| libFilters.la --------| libLooping.la --------| libRemaster.la --------| libbackend.la --------| libfrontend_fox.la ----| |---rezound You might want to take a look at the Makefile.am files following the directory structure shown above to see how this all works. Basically every directory XXX creates it's own libXXX.la file which is then linked in to the final executable in frontend_fox. The frontend_fox directory doesn't use an .la file, but it probably will in the near future. The next sections address specific ways of adding code to the package, specifically Adding to an existing directory, and adding a new directory to the existing structure. A NOTE ABOUT common.h : ----------------------- We use the header config/common.h to address low level portability problems, and include it in every code file. So if you are adding new code, please #include "common.h" at the top of your code files. ADDING SOURCE FILES TO EXISTING DIRECTORY STRUCTURE --------------------------------------------------- Adding a new file to one of the existing directories is a fairly simple thing to do. As an example, let's say we wrote a new effect in src/backend/Effects called EnvelopeFilter.cpp with a header called EnvelopeFilter.h. Your header file also includes the existing file src/backend/CEnvelope.h , so you'll want that listed as a dependency in the Makefile. First off you would open src/backend/Effects/Makefile.am for editing this file builds libEffects.la. Your object file will become part of libEffects.la so the first thing you do is find the line libEffects_la_SOURCES= in Makefile.am. It will look something like this: libEffects_la_SOURCES=CChangeAmplitudeEffect.cpp \ CChangeRateEffect.cpp \ CDelayEffect.cpp \ CFlangeEffect.cpp \ CReverseEffect.cpp \ CStaticReverbEffect.cpp \ CTestEffect.cpp To add your file to the library, all you'll have to do is add it to the list, add a backslash \ with no trailing whitespace to the last file on the list, and put your .cpp file on the next line, the result should look like this. libEffects_la_SOURCES=CChangeAmplitudeEffect.cpp \ CChangeRateEffect.cpp \ CDelayEffect.cpp \ CFlangeEffect.cpp \ CReverseEffect.cpp \ CStaticReverbEffect.cpp \ CTestEffect.cpp \ EnvelopeFilter.cpp Right now you've done enough to build the package with your new file, but before you're done, you'll have to add your header file to make the tarball build process complete. To add the your new header file. find the line EXTRA_DIST in the same Makefile.am. It should look something like this. EXTRA_DIST=CChangeAmplitudeEffect.h \ CChangeRateEffect.h \ CDelayEffect.h \ CFlangeEffect.h \ CReverseEffect.h \ CStaticReverbEffect.h \ CTestEffect.h \ EffectActions.h Here you'll add your header file EnvelopeFilter.h to the end of the list, the same way as above. Now to set up the dependencies the right way. Ok so that's it. Now if you run make, the new Makefile will be created and your new file should be built in. Give it try, if it's not working, make sure you re-read my instructions before asking for help. ADDING NEW DIRECTORIES TO EXISTING STRUCTURE -------------------------------------------- First off read the last section, because there's some instructions there that will be the same in this section. As an example let's say that someone wanted had built an equalizer and wants to add a graphic equalizer controller panel and add it as a new window to the frontend. The E.Q. controller is made of a few different files, lets say: EQSlider.cpp EQChannelPanel.cpp and EQMainWindow.cpp, as well as some corresponding header files. These sources will be a subdirectory of src/frontend_fox called Equalizer Following the conventions used in the other sub directories, we'll compile our sources into one convenience library called libEqualizer.la. The first step will be to write Makefile.am in the Equalizer directory. It will bear a strong resemblance to the other Makefile.am's already in the package, so take a look at src/misc/cc++/Makefile.am now, because it's the smallest. WRITING Makefile.am: -------------------- You'll see that all of my comments in Makefile.am have double pound signs `##'. I use this comment for comments specific to Makefile.am, because it is not passed on to it's resulting Makefile.in or Makefile. If you want a comment to be seen in the final Makefile, use the normal Makefile single pound `#' comment. Ok now, looking at the Makefile.am in src/misc/cc++, you'll see the first non-comment line: include $(top_srcdir)/config/am_include.mk If you are familiar with Makefile rules, you'll know that this will include everything from am_include.mk into our makefile. If you read the previous section, you'll have read the explanation for why we use $(top_srcdir) instead of ../../../config/am_include.mk (If you don't know go back and read the first section like I told you). You can take a look at config/am_include.mk now, but basically it's just CXXFLAGS and LDFLAGS, which are common to the whole package build process. Ok, now the rest of your Makefile.am will follow the same format explained in the previous section (Still haven't read it Huh?, I guess nows a good time!). Now that you've finished writing the Makefile.am for your new directory, you'll still have to incorporate it into the whole build process. First thing to do is drop down to the parent directory, `..' and add your new directory in. So in our example we have a new directory `src/frontend_fox/Equalizer', so we'll have to edit `src/frontend_fox/Makefile.am'. All we have to do here is add Equalizer as a subdirectory for make to descend into during the make process. This is accomplished with the `SUBDIRS' macro. The Makefile.am in this example doesn't have any `SUBDIRS' macro, so we'll just add it: SUBDIRS=Equalizer Although the location isn't important, it will be more readable if you place this somewhere near the top of the file. The next step is to add our new convenience library to the final linking. This takes place in src/frontend_fox/Makefile.am. Open it up now and find the following entry: rezound_LDADD= \ $(top_builddir)/src/PoolFile/libPoolFile.la \ $(top_builddir)/src/backend/Edits/libEdits.la \ $(top_builddir)/src/backend/Effects/libEffects.la \ $(top_builddir)/src/backend/Filters/libFilters.la \ $(top_builddir)/src/backend/Looping/libLooping.la \ $(top_builddir)/src/backend/Remaster/libRemaster.la \ $(top_builddir)/src/backend/libbackend.la \ libfrontend_fox.la This is a list of all the objects that will be linked in to the rezound binary. For our example we would add `Equalizer/libEqualizer.la' to the list. Notice however the use of the $(top_builddir) macro. This macro corresponds to the $(top_srcdir) macro used earlier. But since we're looking for built objects and not sources, we look at the $(top_builddir). So if your new directory had been `src/backend/Filters' your entry would be `$(top_builddir)/src/backend/Filters/libFilters.la'. Ok, we have one final step, and we'll be ready to try everything out. The final step will be to let the `configure' script know about our new Makefile. Briefly, automake turns a Makefile.am into Makefile.in for every Makefile listed in configure.in. Then when configure is run, it transforms all the Makefile.in's into Makefile's. Look at the nearly last entry in the configure.ac : AC_CONFIG_FILES(Makefile src/Makefile src/misc/Makefile src/misc/cc++/Makefile src/PoolFile/Makefile src/backend/Makefile src/backend/Edits/Makefile src/backend/Effects/Makefile src/backend/Filters/Makefile src/backend/Looping/Makefile src/backend/Remaster/Makefile src/frontend_fox/Makefile) It's a list of every Makefile used in the ReZound build. And if you've ever watched a configure script run, you'll notice that the last thing done is to create these Makefiles. Ok so you've probably guessed what to do by now. That's right, add our new Makefile onto the end of the list (Inside the parentheses). That's it. now we have to rebuild our configure script and we're ready to roll. I've included `bootstrap' a nice little script to handle making your configure script. If you're working from a CVS source package you may have already used it. Basically bootstrap removes everything produced by the autotools and re-makes them. So as the last step, run ./bootstrap (from the top source directory). ./configure and make. Hopefully everything works out well, if you are having problems, read this over and make sure you've followed my instructions well. If you still can't get it to work, Feel free to contact us through http://rezound.sourceforge.net. Happy Hacking.