The MagicMakefile, V5
- SVN Link: http://opensource.jdkoftinoff.com/jdks/svn/trunk/magicmakefile/branches/v5
- Source browser: trunk/magicmakefile/branches/v5
- Change log: log
What the magic makefile can do for you
The magic makefile is a powerful way of managing the software build/make process. Effectively it replaces the need for gnu autoconf and automake and is even more automatic.
What does "Even more automatic" mean? It means:
- You don't have to list your source files anywhere. The magicmakefile looks for all appropriate files in the appropriate places
- You don't have to manually manage header file dependencies
- You don't have to manually manage test scripts
- You can easily provide specialized source code for various platforms
However unlike gnu autoconf, it does not spend any time interrogating the system for capabilities. It is up to you, the programmer, to know about the platforms that you support and write code for them.
The magic.mak makefile, and its companion autobuild.sh script allow you to:
- Build a statically linked library with config-tool for ease of use
- Build test programs, example programs, tool programs, and gui programs which use this library
- Run test programs and test scripts automatically, possibly under valgrind
- Build doxygen docs
- Create emacs TAGS and vi tags files from the source code
- Install the resultant binaries, development files, or doxygen docs into a system
- Build a zip or tgz package of the installable files
- Build platform specific packages via the external tools: epm, nsis, or dpkg
- Ship resultant packages or test results to another server via scp
- Easily cross compile the code for mingw32 or embedded linux systems
- Autobuild packages, tests, and ship them from scratch with a single command line for use in autobuild farms
- Create a qmake.pro file so qt/qmake users can build with their tools
- Build gui programs with WxWidgets, GTK, win32 and Mac OS X Cocoa
- Build macosx universal programs and libraries targetting 10.4 (Tiger) or 10.5 (Leopard)
All you have to do make the appropriate subdirs and put your source code in the appropriate directories. Everything else is automatic.
A key point of building programs with the magic makefile is the following:
- All source code in the src directory will be put into a library
- Every source file that has a 'main()' function must live in one of the directories: tools, examples, or tests. A program must be a single source file and it is linked with the library of code in the src directory.
- The gui directory is special and still experimental. You can make subdirs called win32, macosx, macosx-xcode, gtk, wx. How to use these subdirs is not documented yet.
If you want to read about some of the history of the MagicMakefileV5, read the motivation for MagicMakefileV3.
Tutorial
if you want to read a simple step by step tutorial using the MagicMakefile, see the following tutorials:
How It Works
A writeup of the how the magic works will be posted at MagicMakefileV5/HowItWorks?.
Overview
The MagicMakefileV5 is an incremental improvement on MagicMakefileV4 and MagicMakefileV3 - It is fundamentally identical, except that all of the important scripts that are not ever specialized to any specific project live in a directory called autobuild. This directory is standalone, and as such can be referred to via an svn:external or symbolic link. This allows multiple projects to share the same set of autobuild scripts, and any changes committed to one will be available to all other projects.
Getting started
From fresh project without svn
mkdir my_cool_project cd my_cool_project svn export http://opensource.jdkoftinoff.com/jdks/svn/trunk/magicmakefile/branches/v5/autobuild ./autobuild/make_initial_dirs.sh my_cool_project ls -al
Edit the files project.mak and project.sh so that they include the proper descriptions, copyright, and author information.
Put your h files in the include dir, your c++ files (.cpp or .cc) in the src dir, any single c++ file test programs in the tests dir, any single c++ file tools in the tools dir, any single file c++ example programs in the examples dir. In each of these dirs you can make subdirs for posix, macosx, linux, win32, for platform specific source code.
After that you have a few options to build it. During normal development you want to make sure all intermediate generated files are put in a separate dir. Do this by 'mkdir build; cd build'. Then run the *configure* script to generate the primare GNUmakefile. For instance use one of these command lines:
../configure --target-platform-linux=1 # or: ../configure --target-platform-macosx-universal=1
Another way to do a more complex build is with the *autobuild.sh* script:
Run the following for more information:
../autobuild/autobuild.sh --help
There are a lot more features hidden inside the magic makefile! Ask jeffk@… for more info!
Example Use Cases of the MagicMakefile
Create a static library written in C or C++
First, create a dir for your project and grab the magicmakefile files:
mkdir libabcd cd libabcd svn export http://opensource.jdkoftinoff.com/jdks/svn/trunk/magicmakefile/branches/v5/autobuild ./autobuild/make_initial_dirs.sh abcd
Edit your project information in the project.mak and project.sh files.
Next, create your header files and source files:
vim include/abcd_first.h src/abcd_first.cpp
# add some interesting code
Make a subdirectory for intermediate compiler files to build in, and run configure to create a GNUmakefile for posix platforms that will install into the examples folder in your home directory:
mkdir build cd build ../configure --target-platform-posix --prefix=$HOME/examples --debug=1
That configure step created a GNUmakefile and a 'reconfigure' script. To build the library run make. However you may want to try the following for more information:
make help
make compile_info
To build and install, you have three options. You can build and install either:
- The gui and tools programs via make install
- The header files and libraries and config tool via make install-dev
- The doxygen generated html documentation for the source code via make install-docs-dev
The Tools
A quick overview of the command line help for configure, make help and autobuild.sh follow:
configure
$ ./configure --help configure script based on J.D. Koftinoff Software Ltd.'s MagicMake system. See http://opensource.jdkoftinoff.com/jdks/trac/jdks/wiki/MagicMakefileV5 for more information example usage: Step 1: make a directory to put build results in: mkdir b Step 2: cd into this directory: cd b Step 3: run this configure script: ../configure Some example typical command line arguments for configure: Build native binaries on a generic posix machine: ../configure --target-platform-posix=1 Build native binaries on a linux machine: ../configure --target-platform-linux=1 Build native binaries on a mac os x machine: ../configure --target-platform-macosx=1 Build universal binaries on a mac os x machine: ../configure --target-platform-macosx-universal=1 Build on a mac os x machine and cross compile for windows via mingw32 cross compiler ../configure --native-platform-macosx-universal=1 --cross-compiling=1 --compiler-prefix=i386-mingw32- --target-platform-mingw32=1 Build on a linux machine and cross compile for windows via mingw32 cross compiler ../configure --native-platform-linux=1 --cross-compiling=1 --compiler-prefix=i386-mingw32- --target-platform-mingw32=1 Further options for installation path of 'make install' and 'make install-dev' destinations: ../configure --prefix=/opt/local without the --prefix option, the system defaults to $PWD/install - not /usr/local like gnu autoconf would After running the configure stage, a GNUmakefile will be created for you to run with gnu make
make help
$ make help TOP of source is $DIR compile_info : show compile flags, directories, options lib : build library ... TAGS : make etags for emacs tags : make ctags for vi docs : html docs docs-dev : build doxygen docs clean : clean intermediate files distclean / realclean : clean all built files (except docs) tools : build tool programs examples : build example programs tests : build test programs test : run tests, sh scripts and test programs dirs : create output dirs preinstall : install tool executables files into ... preinstall-docs : copy html docs into ... preinstall-dev : install tool executables, include files and library files into ... preinstall-docs-dev : install tool executables, include files, library files, and doxygen docs into ... package : make package of executables package-testresults : make package of test results package-dev : make package of development files package-docs-dev : make package of development doxygen documentation packages : make all packages install : install tool executables files into $PREFIX install-docs : copy html docs into ... install-dev : install tool executables, include files and library files into ... install-docs-dev : install tool executables, include files, library files, and doxygen docs into ... ship : ship main package to another computer via scp, use --ship-to configure option. Currently ... ship-dev : ship dev package to another computer via scp ship-docs-dev : ship dev documentation package to another computer via scp ship-testresults : ship testresults package to another computer via scp ship-raw-testresults : ship testresults files to another computer via scp ship-raw-docs-dev : ship doxygen files to another computer via scp ship-all : ship all packages to another computer via scp
autobuild.sh
$ ../autobuild/autobuild.sh
Autobuild script for the J.D. Koftinoff Software Ltd.'s MagicMake system.
See http://opensource.jdkoftinoff.com/jdks/trac/jdks/wiki/MagicMakefileV5 for more information
Usage:
mkdir work_dir
cd work_dir
project_dir/autobuild/autobuild.sh [target] [platform] [option] [package] [configure flags...]
Where:
[target] is one of:
build
clean
configure
docs
docs-dev
install
install-dev
install-docs-dev
package
package-dev
package-docs-dev
package-testresults
packages
ship
ship-all
ship-dev
ship-docs-dev
ship-raw-testresults
ship-testresults
testresults
[platform] is one of:
cross-linux-ppc
cross-linux-ppc64
cross-mingw32-i386
cross-mingw32msvc-i586
linux
linux-cell_ppu
linux-cell_spu
linux-i386
linux-ppc
linux-ppc64
linux-x86_64
macosx
macosx-i386
macosx-ppc
macosx-ppc64
macosx-universal
macosx-x86_64
mingw32
posix
xenomai
[option] is one of:
debug
debug_optimize
profile
release
[package] is one of:
dpkg
epm
macosx
none
nsis
tgz
zip
useful configure flags:
--target-install-dir=/opt [defaults to ....]
--target-bin-dir=bin
--target-etc-dir=etc
--target-share-dir=share/...
--target-docs-dir=share/doc/...
--target-lib-dir=lib
--package-suffix=-abcd
--ship-to=USERNAME@SERVER:PATH
Platforms
platform specific subdirs
Every source directory may contain subdirectories for platform specific source code. valid directory names include:
- posix
- cygwin
- win32
- mingw32
- linux linux-ppc linux-i386 linux-ppc64 linux-x86_64
- macosx macosx-ppc macosx-i386 macosx-ppc64 macosx-x86_64
- xenomai
- cell_spu
- cell_ppu
These platforms may be selected during configure time with options such as:
../configure --target-platform-posix=1 ../configure --target-platform-mingw32=1 ../configure --target-platform-macosx-universal=1 "--macosx-universal-archs=i386 ppc x86_64 ppc64"
Cross Compiling
Call configure with the target platform, set the "--cross-compiling=1" flag, and set the cross compiler prefix via "--compiler-prefix=..."
