1 The MCS makefiles (-*- outline -*-)
2 Peter Williams <peter@newton.cx>
4 The new makefiles try to abstract building on Windows and Linux. They
5 try to provide a consistent set of ways to express the things that our
6 build system needs to let us do, specifically:
9 * Build libraries and executables easily
10 * Let developers use different runtimes and class libaries
11 * Make distributions easily
12 * Provide a framework for testing
13 * Build platform-independently whenever possible
21 A general makefile looks like this:
23 ========================================
24 thisdir = class/Mono.My.Library
26 include ../../build/rules.make
32 $(MKINSTALLDIRS) $(DESTDIR)$(prefix)/share/
33 $(INSTALL_DATA) myfile.txt $(DESTDIR)$(prefix)/share/myfiledir
36 rm -f my-generated-file
38 test-local: my_test_program.exe
41 $(RUNTIME) my_test_program.exe
43 DISTFILES = myfile.txt my_test_source.cs
45 dist-local: dist-default
47 my_test_program.exe: my_test_source.cs
48 $(CSCOMPILE) /target:exe /out:$@ $<
49 ========================================
51 Each makefile follows the same pattern: it does some setup, includes
52 the standard make rules, and provides rules for six standard targets:
53 all, install, test, run-test, clean, and dist.
55 "Some setup" is defining two variables: $(thisdir) and
56 $(SUBDIRS). $(thisdir) is the directory that the makefile lives in,
57 relative to the top directory (ie, class/corlib) and $(SUBDIRS)
58 defines the subdirectories that should be built in.
60 The six targets do the following:
62 * all-local builds whatever someone would expect to be built
63 when they just type 'make'. Most likely Foo.dll or Foo.exe
65 * install-local installs whatever got built by all-local.
67 * test-local _builds_ the test programs or libraries but does
70 * run-test-local actually runs the tests. It shouldn't
71 necessarily exit in an error if the test fails, but should make that
72 situation obvious. It should only run tests that take care of
73 themselves automatically; interactive tests should have an individual
74 target. The idea is that 'make run-test' from the toplevel should be
75 able to proceed unsupervised and test everything that can be tested in
78 * clean-local removes built files; 'make clean' should leave
79 only files that go into a distribution tarball. (But it is not necessarily
80 true that all files that go into a tarball need to be left after a make clean.)
82 * dist-local copies files into the distribution tree, which is
83 given by the variable $(distdir). dist-local always depends on the
84 target 'dist-default'. See ** 'make dist' below.
90 ** Build configuration
92 In general, MCS needs to be able to build relying only on the
93 existence of a runtime and core libraries (corlib, System,
94 System.Xml). So there shouldn't be any checking for libraries or
95 whatnot; MCS should be able to build out of the box. We try to keep
96 platform detection and feature testing (ie, for HP/UX echo) inside
97 the makefiles; right now, there's no configuration script, and it'd
98 be nice to keep it that way. (I am told that some people build on
99 both Windows and Linux in the same tree, which would be impossible to
100 do if we cached platform-related configury values.)
102 That being said, it's very convenient for developers to be able to
103 customize their builds to suit their needs. To allow this, the
104 Makefile rules are set up to allow people to override pretty much any
107 Configuration variables are given defaults in `config-default.make';
108 `rules.make' optionally includes `$(topdir)/build/config.make', so you
109 can customize your build without CVS trying to commit your modified
110 `config-default.make' all the time. Platform-specific variables are
111 defined in `$(topdir)/build/platforms/$(PLATFORM).make', where
112 $(PLATFORM) is detected in config-default.make. (Currently, the only
113 choices are linux.make and win32.make.)
115 The best way to learn what the configuration variables are is to read
116 `config.make' and `platform.make'. There aren't too many and hopefully
117 they should be self-explanatory; see the numerous examples below for
118 more information if you're confused.
125 ** Recommendations for platform specifics
127 If you find yourself needing a platform-specific customization, try
128 and express it in terms of a feature, rather than a platform test. In
129 other words, this is good:
131 ========================================
132 run-test-local: my-test.exe
133 ifdef PLATFORM_NEEDS_CRAZY_CRAP
136 $(RUNTIME) my-test.exe
137 ========================================
141 ========================================
142 run-test-local: my-test.exe
150 $(RUNTIME) my-test.exe
151 ========================================
153 The latter accumulates and gets unpleasant and it sucks. Granted,
154 right now we only have two platforms, so it's not a big deal, but it's
155 good form to get used to and practice. Anyway, take a look at how we
156 do the various corlib building hacks for examples of how we've done
157 platform-specificity. It certainly isn't pretty, but at least it's a
167 The point of the build system is to abstract things and take
168 care of all the easy stuff. So if you find yourself writing a
169 Makefile, know that there's probably already infrastructure to do what
170 you want. Here are all the common cases I can think of ...
177 * Compiling C# code? use:
179 ========================================
180 my-program.exe: my-source.cs
181 $(CSCOMPILE) /target:exe /out:$@ $^
182 ========================================
186 ========================================
187 my-lib.dll: my-source.cs
188 $(CSCOMPILE) /target:library /out:$@ $^
189 ========================================
191 Note the '$@' and '$^' variables. The former means "the name of the
192 file that I am trying to make" and the latter means "all the
193 dependencies of the file I am trying to make." USE THESE VARIABLES
194 AGGRESSIVELY. Say that you add a new source to your program:
196 ========================================
197 my-program.exe: my-source.cs my-new-source.cs
198 $(CSCOMPILE) /target:exe /out:$@ $^
199 ========================================
201 Because of the $^ variable, you don't need to remember to add another
202 file to the command line. Similarly, if you rename your program, you
203 won't need to remember to change the rule:
205 ========================================
206 MonoVaporizer.exe: my-source.cs my-new-source.cs
207 $(CSCOMPILE) /target:exe /out:$@ $^
208 ========================================
210 will still work. Another useful variable is $<, which means "the first
211 dependency of whatever I'm building." If you order your dependencies
212 carefully it can be extremely useful.
218 * Just building an executable? use:
220 ========================================
221 PROGRAM = myprogram.exe
222 LOCAL_MCS_FLAGS = /r:System.Xml.dll
224 include ../build/executable.make
225 ========================================
227 executable.make builds a program in the current directory. Its name is
228 held in $(PROGRAM), and its sources are listed in the file
229 $(PROGRAM).sources. It might seem to make more sense to just list the
230 program's sources in the Makefile, but when we build on Windows we
231 need to change slashes around, which is much easier to do if the
232 sources are listed in a file. The variable $(LOCAL_MCS_FLAGS) changes
233 the flags given to the compiler; it is included in $(CSCOMPILE) so you
234 don't need to worry about it.
236 executable.make does a lot for you: it builds the program in 'make
237 all-local', installs the program in $(prefix)/bin, distributes the
238 sources, and defines empty test targets. Now, if your program has a
239 test, set the variable HAS_TEST:
241 ========================================
242 PROGRAM = myprogram.exe
243 LOCAL_MCS_FLAGS = /r:System.Xml.dll
245 include ../build/executable.make
247 test-local: mytester.exe
249 run-test-local: mytester.exe
252 mytester.exe: mytester.cs
253 $(CSCOMPILE) /target:exe /out:$@ mytester.cs
254 ========================================
256 If your program has 'built sources', that is, source files generated
257 from other files (say, generated by jay), define a variable called
258 BUILT_SOURCES and do *not* list the sources in $(PROGRAM).sources:
260 ========================================
261 PROGRAM = myprogram.exe
262 LOCAL_MCS_FLAGS = /r:System.Xml.dll
263 BUILT_SOURCES = parser.cs
264 CLEAN_FILES = y.output
266 include ../build/executable.make
268 parser.cs: parser.jay
269 $(topdir)/jay/jay $< > $@
270 ========================================
272 executable.make will automatically delete the $(BUILT_SOURCES) files
273 on 'make clean'. Since this situation is a common occurrence and jay
274 happens to leave behind y.output files, you can also define a variable
275 called $(CLEAN_FILES) that lists extra files to be deleted when 'make clean' is
276 called. (That's in addition to your executable and the built sources).
283 * Buildling a library? Use
285 ========================================
286 LIBRARY = Mono.MyLib.dll
287 LIB_MCS_FLAGS = /unsafe
288 TEST_MCS_FLAGS = /r:System.Xml.dll
290 include ../../build/library.make
291 ========================================
293 Where you library is called $(LIBRARY); it will be put into
294 $(topdir)/class/lib. LIB_MCS_FLAGS is the set of MCS flags to use when
295 compiling the library; in addition, a global set of flags called
296 $(LIBRARY_FLAGS) is added (that variable is defined in
297 config-defaults.make), as well as the usual $(LOCAL_MCS_FLAGS).
299 As in executable.make, the sources for your library are listed in
300 $(LIBRARY).sources. Note: these source lists should have Unix forward
301 slashes and Unix newlines (\n, not \r\n.) If you get an error about
302 "touch: need a filename", that means your .sources file doesn't end in
303 a newline. It should.
305 Now library.make also assumes that your library has an NUnit2 test
306 harness. The files should be in a subdirectory called Test/, and if
307 your library is called Mono.Foo.dll, they should be listed in
308 Mono.Foo_test.dll.sources. The names in that files should *not* have
309 the Test/ prefix. 'make test' will build Mono.Foo_test.dll in the
310 current directory, automatically supplying the flags to reference the
311 original library and NUnit.Framework.dll.
313 If you don't have a test, just do this:
315 ========================================
316 LIBRARY = Mono.MyLib.dll
317 LIB_MCS_FLAGS = /unsafe
320 include ../../build/library.make
321 ========================================
323 and feel ashamed. Every good library has a test suite!
325 Extra flags needed to compile the test library should be listed in
326 $(TEST_MCS_FLAGS); often you will have a line like this:
328 ========================================
329 TEST_MCS_FLAGS = $(LIB_MCS_FLAGS)
330 ========================================
332 Again, library.make does a lot for you: it builds the dll, it
333 generates makefile fragments to track the dependencies, it installs
334 the library, it builds the test dll on 'make test', it runs
335 $(TEST_HARNESS) on it on 'make run-test', it removes the appropriate
336 files on 'make clean', and it distributes all the source files on
337 'make dist'. (TEST_HARNESS defaults to be nunit-console.exe but it may
338 be overridden to, say, nunit-gtk). If you have extra files to
339 distribute when using either library.make or executable.make, use the
340 variable $(EXTRA_DISTFILES):
342 ========================================
347 ========================================
349 Again, library.make and executable.make do the right things so that we
350 can build on Windows, doing some trickery to invert slashes and
351 overcome command-line length limitations. Use them unless you have a
352 really good reason not to. If you're building a bunch of small
353 executables, check out tools/Makefile or tools/security/Makefile; if
354 all the files are in the current directory, changing slashes isn't a
355 big deal, and command-line lengths won't be a problem, so
356 executable.make isn't necessary (and indeed it won't work, since it
357 can only build one .exe in a directory).
359 If you're building a library, library.make is highly recommended; the
360 only DLL that doesn't use it is corlib, because building corlib is a
361 fair bit more complicated than it should be. Oh well.
368 * Running a C# program? Use $(RUNTIME)
370 ========================================
371 run-test-local: myprog.exe
372 $(RUNTIME) myprog.exe
373 ========================================
375 $(RUNTIME) might be empty (if you're on windows), so don't expect to
376 be able to give it any arguments. If you're on a platform which has an
377 interpreter or jitter, $(RUNTIME_FLAGS) is included in $(RUNTIME), so
380 $(TEST_RUNTIME) is the runtime to use when running tests. Right now it's
385 * Calling the compiler directly? Use $(MCS).
387 Really, you should use $(CSCOMPILE) whenever possible, but $(MCS) is
388 out there. $(BOOTSTRAP_MCS) is the C# compiler that we use to build
389 mcs.exe; on Linux, we then use mcs.exe to build everything else, but
390 on Windows, we use csc.exe to build everything. Only use
391 $(BOOTSTRAP_MCS) if you know what you're doing.
397 * Compiling C code? Use $(CCOMPILE)
399 To give it flags, set $(LOCAL_CFLAGS). As with compiling C#, the
400 variable $(CFLAGS) will automatically be included on the command line.
406 * Installing files? Use $(MKINSTALLDIRS), $(INSTALL_DATA) or
407 $(INSTALL_BIN), $(prefix), and $(DESTDIR).
409 Every time a file is installed the commands should look like this:
411 ========================================
413 $(MKINSTALLDIRS) $(DESTDIR)$(prefix)/my/dir
414 $(INSTALL_DATA) myfile $(DESTDIR)$(prefix)/my/dir
415 ========================================
417 This way the directory is created recursively if needed (admittedly, we could
418 probably rely on mkdir -p), the file is given the correct permissions,
419 the user can override $(MKINSTALLDIRS) and $(INSTALL) if they need to,
420 and we can support $(DESTDIR) installs. We use $(DESTDIR) to make
421 monocharge tarballs, and it's useful otherwise, so try and use it
428 * 'make dist'? Use $(DISTFILES)
430 The 'dist-default' target will copy the files listed in $(DISTFILES)
431 into the distribution directory, as well as Makefile and ChangeLog if
432 they exist. This is almost always all that you need, so ideally your
433 make dist support should only be:
435 ========================================
436 DISTFILES = README Test/thoughts.txt
438 dist-local: dist-default
439 ========================================
441 DISTFILES will cope correctly with files in subdirectories, by the
442 way. Note that if you put a nonexistant file or a directory in
443 DISTFILES it will *not* complain; it will just ignore it.
445 If you want to test your 'make dist' code, you can try
447 ========================================
448 $ cd class/Mono.MyClass
449 $ make dist-local distdir=TEST
450 ========================================
452 And your files should be copied into TEST/ in the current directory.
453 There is a toplevel 'make distcheck' target, which will build a dist
454 tarball, try to build it, install files to a temporary prefix, make
455 clean it, make a distribution, and compare the files left over to the
456 files originally in the tarball: they should be the same. But this
457 takes about 15 minutes to run on my 1.1 Ghz computer, so it's not for
464 * Lots of files? Use $(wildcard *.foo)
466 When specifying the sources to a library or executable, wildcards are
467 not encouraged; in fact they're not allowed if you use library.make or
468 executable.make. But there are times when they're useful, eg:
470 ========================================
471 DISTFILES = $(wildcard Test/*.in) $(wildcard Test/*.out)
472 ========================================
474 Just so you know that 'make' has this feature.
481 * Referencing files in other directories? Use $(topdir).
483 $(topdir) is the path to the top directory from the current build
484 directory. Basically it's a sequence of ../.. computed from the value
485 that you give $(thisdir) at the top of your Makefile. Try to reference
486 things from $(topdir), so your code can be moved or cut-and-pasted
487 around with a minimum of fuss.
494 * Conditional building? Use ifdef/ifndef/endif
496 Now in general we want to avoid conditional building, but sometimes
497 something doesn't work on Linux or already exists on Windows or
498 whatnot. (See below on recommended form for how to build
499 platform-specifically.) GNU Make supports the following construction:
501 ========================================
502 BUILD_EXPERIMENTAL = yes
504 ifdef BUILD_EXPERIMENTAL
505 experimental_stuff = my-experiment.exe
510 all-local: my-sane.exe $(experimental_stuff)
511 ========================================
513 'ifdef' means 'if the variable is set to nonempty', so you could have
515 ========================================
516 BUILD_EXPERIMENTAL = colorless green ideas sleep furiously
517 ========================================
519 and Make would be happy. I hope that the meaning of 'ifndef' should be
520 obvious. If you want to only sometimes build a target, the above
521 construction is the recommended way to go about it; it's nice to have
522 the rules exist in a Makefile even if they aren't invoked.
524 If you want to see why conditionals aren't nice, take a look at
525 library.make or class/corlib/Makefile.
531 * 'Private' directories that shouldn't be built by default? Use DIST_ONLY_SUBDIRS
533 Several of the MCS class libraries have demo or experimental
534 implementations that depend on things not included with MCS (say,
535 Gtk#). We don't want to build them by default, because the user might
536 not have those dependencies installed, but it's nice to have a
537 Makefile for them to be built nicely.
539 First of all, there's nothing stopping you from writing a Makefile for
540 such a directory; just don't put it in the SUBDIRS line of its parent
541 directory. That way, you can do all the normal build things like 'make
542 all' or 'make clean' in that directory, but people trying to bootstrap
543 their system won't run into problems.
545 At the same time you probably want to include this directory in the
546 distribution so that people can use your demo or experimental code if
547 they know what they're doing. Hence the variable
548 $(DIST_ONLY_SUBDIRS). As you might guess, it's like the SUBDIRS
549 variable: it lists subdirectories that a regular shouldn't recurse
550 into, but should have their 'make dist' rules invoked.
552 Say you've written Mono.MyFancyLib.dll and you have
553 a demo app using Gtk# called MyFancyDemo. The Makefile rules might
556 class/Mono.MyFancyLib/Makefile
557 ========================================
558 thisdir = class/Mono.MyFancyLib
560 DIST_ONLY_SUBDIRS = MyFancyDemo
561 include ../../build/rules.make
563 LIBRARY = Mono.MyFancyLib.dll
564 LIB_MCS_FLAGS = /r:System.dll
565 TEST_MCS_FLAGS = $(LIB_MCS_FLAGS)
567 include ../../build/library.make
568 ========================================
570 class/Mono.MyFancyLib/MyFancyDemo/Makefile
571 ========================================
572 thisdir = class/Mono.MyFancyLib/MyFancyDemo
574 include ../../../build/rules.make
576 PROGRAM = FancyDemo.exe
577 LOCAL_MCS_FLAGS = /r:gtk-sharp.dll
579 include ../../../build/executable.make
580 ========================================
585 * Special recursion needs? Use OVERRIDE_BARE_TARGETS
587 By default, rules.make defines the all, install, clean, etc. targets
588 to look something like this:
590 all: all-recursive all-local
592 Sometimes that doesn't cut it; say for example you want to check for
593 something before doing a lengthy recursive build (see
594 $(topdir)/Makefile) or you have a something like this
598 class/MyLibrary/Test:
599 Build TestMyLibrary.exe
601 'make clean test' will fail here, because the build will happen in
602 the Test subdirectory first, so there will be no MyLibrary.dll to link
603 against. (Unless you write a nasty evil relative path rule which is
604 strongly discouraged.)
606 Anyway, to solve this problem you can do
608 ========================================
609 OVERRIDE_BARE_TARGETS = yes
610 thisdir = class/MyLibrary
612 include ../../build/rules.make
614 # This is normally "all-recursive all-local"
615 all: all-local all-recursive
617 test: test-local test-recursive
619 ========================================
625 ** A few implementation details
627 The way rules.make does its recursion is very standard; it maps
628 {all,install,clean, dist,test} to $@-recursive, which executes that
629 rule in each directory in $(SUBDIRS), and then calls $@-local in the
630 current directory. So something that gets built in a subdirectory
631 cannot rely on something that gets built in its parent directory. If
632 this is a problem, see the bit about using OVERRIDE_BARE_TARGETS;
633 since the recursive rules do $(MAKE) $* in their subdirectories,
634 changing the 'all' target will do the right thing in a recursive
635 build. Note that the recursive rule for 'dist' is different; it makes
636 dist-recursive in subdirectories, so you at least have to define that
637 rule, even if you use OVERRIDE_BARE_TARGETS.
639 Note that even a directory that doesn't, for example, have any tests
640 must still define test-local; otherwise 'make test' run from the
641 toplevel directory will break.
650 We want to make it so that the user can specify certain flags to
651 always be given to a tool, so there's a general way of implementing
654 * $(foo_FLAGS) remains unset or defaulted to something
655 sensible; the user can provide overrides this way.
657 * $(LOCAL_foo_FLAGS) is set in a specific Makefile to
658 provide necessary values.
660 * $(PLATFORM_foo_FLAGS) is set in the platform configuration
661 to provide platform-specific values.
663 * $(PROFILE_foo_FLAGS) is set in the profile configuration
664 to provide profile-specific values.
666 * $(USE_foo_FLAGS) is defined to be the combination of all of
667 the above, and it's what is actually passed to $(foo).
669 $(MCS_FLAGS) and $(CFLAGS) follow this model. If you end up finding
670 that another tool is used commonly (hm, jay...), please follow this form.
679 Always use the icky Windows /argument way of passing parameters to the C#
680 compiler so that csc can be used.
682 Always use /r:foo.dll, not /r:foo. Windows requires the former.
684 Use /r:$(corlib), not /r:corlib.
686 If you're writing shell script code as part of a make rule, remember
687 that Windows has command-line length limits. So something like
689 ========================================
690 mytool $(all_the_sources_to_corlib)
691 ========================================
693 Is probably going to cause problems. As I understand it,
695 ========================================
696 for f in $(all_the_sources_to_corlib) ; do ...
697 ========================================
699 is ok, since the shell itself doesn't have those limitations. Other
700 than that, you should still try to write fairly portable shell
701 script. Linux and Cygwin both use the GNU utilities, but there's at
702 least one hardy soul trying to build Mono on HP/UX, and no doubt there
703 will be ports to more Unices as time goes on.
712 We still don't use /d:NET_1_1 ; it causes some build problems right
715 There's a hack in class/System.Data/Makefile to work around a very
716 strange crash in the runtime with some custom attribute stuff. It'd be
719 Also, there's a /lib:$(prefix)/lib in the System.dll Makefile, which
720 is for some reason necessary if System.Xml.dll hasn't been built yet.
721 (Well, it's necessary because of the /r:System.Xml.dll, but that
722 should be in the search path, it seems.)
724 A lot of the weird targets in the old makefiles have been dropped; I
725 have a feeling that a lot of them are archaic and not needed anymore.
727 I'd really like to write a build tool in C#. It would be nice to have
728 something really extensible and well-designed and clean. NAnt is,
729 IMHO, an apalling abomination and a tragically bad attempt at solving
730 the software building problem. Just so you know.
732 (On the other hand, NUnit is really neat.)