* Make distributions easily
* Provide a framework for testing
* Build platform-independently whenever possible
-
-
+ * Generate, update, and build monodoc documentation.
run-test-local:
$(RUNTIME) my_test_program.exe
+run-test-ondotnet-local:
+ $(RUNTIME) my_test_program.exe
+
DISTFILES = myfile.txt my_test_source.cs
dist-local: dist-default
+doc-update-local:
+
my_test_program.exe: my_test_source.cs
$(CSCOMPILE) /target:exe /out:$@ $<
========================================
Each makefile follows the same pattern: it does some setup, includes
-the standard make rules, and provides rules for six standard targets:
-all, install, test, run-test, clean, and dist.
+the standard make rules, and provides rules for eight standard targets:
+all, install, test, run-test, clean, dist, and doc-update.
"Some setup" is defining two variables: $(thisdir) and
$(SUBDIRS). $(thisdir) is the directory that the makefile lives in,
relative to the top directory (ie, class/corlib) and $(SUBDIRS)
defines the subdirectories that should be built in.
-The six targets do the following:
+The eight targets do the following:
* all-local builds whatever someone would expect to be built
when they just type 'make'. Most likely Foo.dll or Foo.exe
able to proceed unsupervised and test everything that can be tested in
such a manner.
+ * run-test-ondotnet-local is a variant of run-test-local. It is used only to validate if our tests themselves works fine under Microsoft runtime (on Windows). Basically, in this target, we should not use $(TEST_RUNTIME) to test our libraries.
+
* clean-local removes built files; 'make clean' should leave
only files that go into a distribution tarball. (But it is not necessarily
true that all files that go into a tarball need to be left after a make clean.)
given by the variable $(distdir). dist-local always depends on the
target 'dist-default'. See ** 'make dist' below.
+ * doc-update-local should generate or update monodoc documentation,
+if appropriate. This is usually only appropriate for libraries. It's
+defined as a standard target so that it can easily be run recursively
+across all libraries within the module.
+
$(CSCOMPILE) /target:exe /out:$@ mytester.cs
========================================
+If your program has NUnit tests, set the variable HAS_NUNIT_TEST:
+
+========================================
+PROGRAM = myprogram.exe
+LOCAL_MCS_FLAGS = /r:System.Xml.dll
+HAS_NUNIT_TEST = yes
+include ../build/executable.make
+========================================
+
+HAS_NUNIT_TEST tests follow library.make NUnit test conventions:
+the files should be in a subdirectory called Test/, and if
+your program is called myprogram.exe, they should be listed in
+myprogram_test.dll.sources. The names in that files should *not* have
+the Test/ prefix. 'make test' will build myprogram_test_$(PROFILE).dll
+in the current directory, automatically supplying the flags to
+reference the original program and NUnit.Framework.dll.
+
If your program has 'built sources', that is, source files generated
from other files (say, generated by jay), define a variable called
BUILT_SOURCES and do *not* list the sources in $(PROGRAM).sources:
only DLL that doesn't use it is corlib, because building corlib is a
fair bit more complicated than it should be. Oh well.
+library.make also automatically supports generating and updating
+monodoc documentation. Documentation is stored within the
+Documentation directory (a sibling to the Test directory), and is
+generated/updated whenever the doc-update target is executed.
+Assembling of the documentation so that the monodoc browser can
+display the documentation is handled separately within the mcs/docs
+all-local target; see mcs/docs/Makefile for details.
+
variable $(CFLAGS) will automatically be included on the command line.
+* Compiling resources with resgen
+
+If you have a resource that should be compiled with resgen and
+included in your assembly, you can use the RESOURCES_DEFS variable.
+This variable can contain lists of pairs that are separated by comma
+to represent the resource ID as embedded in the assembly followed by
+the file name, like this:
+
+RESOURCE_DEFS = Messages,TextResources.resx Errors,ErrorList.txt
+
+
+* Documentation-related needs? Use $(MDOC)
+
+$(MDOC) is a front-end to the monodoc documentation system, supporting
+documentation generation, updating, importing from Microsoft XML
+Documentation and ECMA documentation formats, assembling documentation
+for use within the monodoc documentation browser, and exporting
+documentation to various other output formats such as static HTML.
+
+It is currently only used for library.make's doc-update-local target
+and for assembling documentation within $topdir/docs.
+
+
-* Special recursion needs? Use OVERRIDE_BARE_TARGETS
+* Special recursion needs?
By default, rules.make defines the all, install, clean, etc. targets
to look something like this:
- all: all-recursive all-local
+ all: all-recursive
+ $(MAKE) all-local
Sometimes that doesn't cut it; say for example you want to check for
something before doing a lengthy recursive build (see
Anyway, to solve this problem you can do
========================================
-OVERRIDE_BARE_TARGETS = yes
thisdir = class/MyLibrary
SUBDIRS = Test
include ../../build/rules.make
-# This is normally "all-recursive all-local"
-all: all-local all-recursive
+# Normally, make runs 'all-recursive' first, and then 'all-local'
+# With this, we ensure that 'all-local' is executed first.
+all-recursive: all-local
-test: test-local test-recursive
+test-recursive: test-local
...
========================================
** A few implementation details
The way rules.make does its recursion is very standard; it maps
-{all,install,clean, dist,test} to $@-recursive, which executes that
-rule in each directory in $(SUBDIRS), and then calls $@-local in the
-current directory. So something that gets built in a subdirectory
-cannot rely on something that gets built in its parent directory. If
-this is a problem, see the bit about using OVERRIDE_BARE_TARGETS;
-since the recursive rules do $(MAKE) $* in their subdirectories,
-changing the 'all' target will do the right thing in a recursive
-build. Note that the recursive rule for 'dist' is different; it makes
-dist-recursive in subdirectories, so you at least have to define that
-rule, even if you use OVERRIDE_BARE_TARGETS.
+{all,install,clean, dist,test} to $@-recursive, which executes that rule
+in each directory in $(SUBDIRS), and then calls $@-local in the current
+directory. So something that gets built in a subdirectory cannot rely on
+something that gets built in its parent directory. If this is a problem,
+see the previous section. Note that the recursive rule for 'dist' is
+different; it makes dist-recursive in subdirectories, so you at least
+have to define that rule.
Note that even a directory that doesn't, for example, have any tests
must still define test-local; otherwise 'make test' run from the