Personal tools
You are here: Home documentation developer Pd-extendedBuildSystem
Views

Edit history

Edit: -1 of 1
Time: 2014-05-22 15:57:30
Note: /pd/pd/docs/developer/PdExtendedBuildSystem/vote

changed:
-
----

This document gives an overview of the Pd-extended build system for externals.  You can find many working examples in '''externals/Makefile'''.  You can find more information on related topics here: [[Directory Layout]], [[RepositoryLayout]], [GettingPdSource], etc.

== Basic Layout ==

At the root of each main section of the whole source tree (abstractions, doc, externals, packages), there is a '''Makefile'''.  Each '''Makefile''' does the overarching build for that section, while '''packages/Makefile.buildlayout''' specifies all of the locations, common variables, etc.  It is possible to override '''Makefile.buildlayout''' by setting the ''BUILDLAYOUT_DIR'' variable when running ''make''

'''packages/Makefile''' works by calling all of the other '''Makefile'''s in the other SVN sections

For a given package type, Mac OS X Pd.app for example, there is a separate subdirectory '''packages/darwin_app''' with its own '''Makefile''' and files distinct to that platform and package.


=== Exceptions ===

For various reasons, there are some exceptions to the above rules: flext, gem, and pd.  These can all be included using targets in '''packages/Makefile'''

== How to add your library ==

Once you've decided to take your library through the process of [[Getting Into Pd extended]], the best way to start is to build your library using the [[Library Template]].  This template gives you a easily working build system for all supported Pd platforms (many, many) and makes it easy to package into a Debian `.deb`, Fedora, `.rpm`, etc. 

== Makefile targets ==


To add your objects to this build system, first make your own targets
and add it to the '''all:''' and '''install:''' targets.  For example:
for the RRADical objects, there is a target called '''rradical_install:'''
which does everything needed to install the RRADical objects.  This
includes installing help patches and any other
documentation. '''rradical_install:''' calls '''rradical:''' to build
anything that needs to be built before being installed.  There is also a clean target for each library, e.g. '''rradical_clean'''.


 mylibrary::
 :: All steps necessary to build your library go in this target.  Once this target is complete, everything should be ready to install.
 mylibrary_install::
 :: The installation of all files happens in this target.
 mylibrary_clean::
 :: This target should remove every single file installed by mylibrary_install, and any build products, like .o files, etc.



== Explanations of Terms ==


 MYLIBRARY_NAME = mylibrary:: 
 :: At the top of each library's section in the '''Makefile''', you will see a variable '''MYLIBRARY_NAME'''.  This variable is the name used to install the abstractions.  This should be all lowercase since its used in the loading of objects within Pd (e.g. ''[mylibrary/myobject]'').
	

 $(objectsdir):: 	    
 :: If your project consists of objects that are meant to be reused in other patches rather than used as a application, then they should go into this directory.  They should be in a directory with a distinct name.  This will be the name of your library of objects, which can be added to the path, or called directly (e.g. [mylibrary/myobject]).
 :: The subdirectory name (e.g. '''mylibrary''') should always be all lowercase.

 $(helpdir):: 
 :: All help patches should go into this directory in a subdirectory with the same nameas the subdirectory for your objects.  For example, for ''[mylibrary/myobject]'' above, the helpfile would be '''mylibrary/myobject-help.pd'''.
 :: The subdirectory name (e.g. '''mylibrary''') should always be all lowercase.
	


 $(manualsdir):: 
 :: If you have any other kinds of documentation, like a text or HTML manual, or a Pd-based tutorial, then it should go into this directory, again in a subdirectory with the same name as the library or application. Using the previous example again, the <i>mylibrary</i> manual would be '''mylibrary/mylibrary.html'''.
 :: The subdirectory name (e.g. '''mylibrary''') should always be all lowercase.



 $(examplesdir):: 
 :: If your project has a examples patches or applications that are meant to be run directly, then it should go into this directory within its own subdirectory.  This directory is a browsable collection of applications.  If your application has a lot of files associated with it, put a main patch and have the extra files in a subdirectory.
 :: '''rradical/usecases/showcase''' is a good example of this.
	


 $(manualsdir):: 
 :: If your project as a manual, then it should be installed into the $(manualsdir) in a folder using the name set in $(MYLIBRARY_NAME).




 $(readmesdir):: 
 :: If your project just has a README, then it should be installed into the $(readmesdir) and not in the $(manualsdir).  If there is a manual also, then the README should go into the $(manualsdir).  The README should go straight into $(readmesdir) with name set in $(MYLIBRARY_NAME).txt

{{{
	install -p $(externals_src)/mylibrary/README \
		$(readmesdir)/$(MYLIBRARY_NAME).txt
}}}


== Adding files not maintained in SVN ==


Sometimes, you can't compile something, but you have a binary you want to throw in.  The target ''' noncvs_install''' will  install the files that are placed in the <i>noncvs</i> tree.  There are only platform-specific directories in the this section since binaries will always be platform-specific.  The <i>noncvs</i> tree mimics the standard Pd layout.  For example, on Mac OS X, you currently have '''packages/noncvs/darwin/bin''', '''packages/noncvs/darwin/extra''', and '''packages/noncvs/darwin/doc/5.reference''' as possible locations to add your files. 



'''noncvs_install''' is automatically used when you do a ''make install'' in '''packages'''.

= Chain of Makefiles =

The Pd-extended build starts in the platform-specific directory in '''packages''', the main three are '''packages/darwin_app''', '''packages/linux_make''', and '''packages/win32_inno'''.  This then maps how how each Makefile calls the others:

{{{
packages/_______/Makefile
                    |
                    \_packages/Makefile
                                     |
                                     |_pd/src/configure
                                     |_Gem/src/configure
                                     |_abstractions/Makefile
                                     |_doc/Makefile
                                     \_externals/Makefile
                                              |
                                              \_externals/&mdash;/Makefile
}}}


Powered by IEM Powered by Plone Section 508 WCAG Valid XHTML Valid CSS Usable in any browser