* Make distributions easily
* Provide a framework for testing
* Build platform-independently whenever possible
-
-
+ * Generate, update, and build monodoc documentation.
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 seven 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 seven 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
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.
+
`rules.make' optionally includes `$(topdir)/build/config.make', so you
can customize your build without CVS trying to commit your modified
`config-default.make' all the time. Platform-specific variables are
-defined in `$(topdir)/build/platforms/$(PLATFORM).make', where
-$(PLATFORM) is detected in config-default.make. (Currently, the only
+defined in `$(topdir)/build/platforms/$(BUILD_PLATFORM).make', where
+$(BUILD_PLATFORM) is detected in config-default.make. (Currently, the only
choices are linux.make and win32.make.)
The best way to learn what the configuration variables are is to read
$(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
projects / mono.git / blobdiff