$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.


