Managing Sub-Projects

Jamfiles can call other Jamfiles that manage individual subprojects. Suppose you have 5 directories, where each directory has its own jamfile and can build a separate library or executable. There may be dependencies between some of these sub-projects. This is easy to do:

SubProject lib1 ; 
SubProject lib2 ; 
SubProject lib3 ; 
SubProject app1 : lib1 lib2 ;
SubProject app2 : lib1 lib3 ;

With the jamfile above you can now build all the libraries and applications by running KJam in the parent directory. You can build any individual sub-project and the projects it depends on by running KJam with the name of the sub-project as the target. KJam will build the sub-projects in the right order. You can also switch to any individual sub-project directory to build and test just that sub-project.

A clean target is also automatically created. Building clean will clean all the sub-projects.

When building a sub-project KJam will invoke a copy of itself in the subproject's directory and will build the default all target. To have KJam build other targets as well, list those as the third argument to the SubProject rule:

SubProject app1 : lib1 lib2 : all verify install ;

It is also possible to make multiple SubProject targets each of which builds a particular sub-project target:

SubProject app1 : lib1 lib2 ; 		// build the 'all' target 
SubProject app1 : lib1 lib2 : verify ; 	// build the 'verify' target 
SubProject app1 : lib1 lib2 : install ; // build the 'install' target 

Now you can invoke each of those targets in the given subproject from the main build file. Here is a jamfile which builds all your sub-projects, and has an install target:

SubProject lib1 ; 
SubProject lib2 ; 
SubProject lib3 ; 
SubProject app1 : lib1 lib2 ; 
SubProject app2 : lib1 lib3 ; 


SubProject <install>app1 : app1 : install ; 
SubProject <install>app2 : app1 : install ; 

Group all : lib1 lib2 lib3 app1 app2 ; 
Group install : <install>app1 <install>app2 ;

Note that you override the automatically created all target to exclude the install sub-project targets. Also notice that the install targets depend on their respective applications being up-to-date.

Given the jamfile above, here are some commands you can run and what they would do:

kjam 			# re-build all the libraries and applications 
kjam lib2 		# re-build just lib2 
kjam app2 		# re-build app2 and its dependents lib1 and lib3 
kjam clean 		# clean all the sub-projects 
kjam install 		# re-build all the applications, and install them all 
kjam "<install>app1" 		# re-build app1, lib1 and lib2, and then install just app1

Try KJam and let me know what you think. It will really help us to refine it.