|
|
Syntax
'tcbuild' works much like 'ant', in that it basically accepts a set of targets to run. However, it's a bit more sophisticated:
- You can set various build properties by simply including 'name=value' pairs on the command line; you can put these anywhere on the command line - anything that looks like 'name=value' gets set and stripped out before the command line is interpreted as a set of targets.
- These properties can also be set in code/base/build-config.global and code/base/build-config.local; the command line overrides build-config.local, which, in turn, overrides build-config.global. Only properties that should be set for everybody go in build-config.global (which is checked in); you can put properties that you want to be set for you and you alone in build-config.local.
- Some targets take arguments, which you simply list on the command line after that target. For example, 'check_one' takes the name of a test to run; you can do 'check_one FooTest check_one BarTest' to run these two tests back-to-back.
- Some targets take a variable number of arguments; this means that this target must be the last target on the command line, and anything after it (other than name=value pairs) will be interpreted as an argument. For example, 'run_class' runs a class (its first argument); anything after its first argument will be passed on to that class as normal command-line arguments.
Targets
Basics
- clean removes absolutely everything the buildsystem can build - classes, test results, boot JARs, and so on. (This consists of nuking the code/base/build directory.)
- clean_tests removes all testruns (results of tests, temp files, etc.); it does ~not~ remove any compiled class files, however.
- compile compiles all the code. This is an incremental compile, so it should be reasonably quick once you've compiled everything once. (Any remaining delays are just in the 'javac' Ant task comparing the .class and .java files' timestamps, not in the buildsystem itself.)
- show_modules dumps out a list of all the modules the system knows about. (This is basically the processed version of what's in 'modules.def.yml'.)
Testing
- check_one runs a single test. It takes one argument - the name of the test to run. Just give it the class name itself (e.g., 'FooTest'), without .java or .class on the end, without a package prefix. It'll find it.
- check runs ~all~ the tests. However, it obeys several different properties (name=value pairs on the command line):
- check_modules (a.k.a. 'check_module'): a comma-delimited list of the modules to run tests from. If you leave this off, it runs tests from all modules.
- check_module_groups (a.k.a. 'check_module_group'): if (and only if!) 'check_modules' is not specified, a list of the "module groups" to run tests from. You can find module groups at the bottom of 'modules.def.yml'. This is just a succinct way of specifying large numbers of modules at once.
- check_types (a.k.a. 'check_type'): A comma-separated list of the types of tests to run - unit, system, or both ('unit,system').
- check_patterns (a.k.a. 'check_pattern'): A comma-separated list of the patterns of test names to run. By default, this is '<asterisk<Test'.
- test_timeout: The timeout for ~each~ individual JUnit test case (i.e., test class), in seconds. Overrides any other value that is set.
- jvmargs: Additional JVM arguments to pass to the VM that runs the test, separated by commas.
- check_file runs a set of tests as specified in a file. It takes one argument - the name of the file of tests to run. Each line of the file can be blank, a comment (starting with '#'), or the name of a test. You can include the package, or leave it off if you want (e.g., either 'com.tc.util.AssertTest' or just 'AssertTest' works); don't include .class or .java on the end.
- check_list runs a set of tests for each test subtree, as specified in a file called '<modulename</tests.(unit|system).lists.<listname>' for each module. For example, if you create files called 'common/tests.unit.lists.foo' and 'legacy-test-tree/tests.system.lists.foo', then 'tcbuild check_list foo' will run the tests named in those files. For subtrees (tests.unit or tests.system) that don't have these files, no tests will be run.
- check_short runs 'check_list short' - in other words, runs all tests in files called '<modulename>/tests.unit.lists.short' and '<modulename>/tests.system.lists.short'. The idea is to limit these files to a fairly short-running, 'sanity check' set of tests for each tree - so developers can run a reasonably-quick set of tests before checking in.
- Implicit targets: 'check_<groupname>', where <groupname> is the name of a 'module group' defined at the end of the 'modules.def.yml' file, will run all tests on all modules in that group. 'check_<groupname>unit' will run all unit tests on modules in that group, and 'check<groupname>_system' will run all system tests on modules in that group. Hence, if you create a group called 'foo' in 'modules.def.yml', suddenly you magically have 'check_foo', 'check_foo_unit', and 'check_foo_system' groups.
- recheck: This is a particularly useful target - it re-runs whichever tests failed on your last test run. (You can set the 'testrun' parameter - e.g., 'testrun=testrun-0015' - to run tests that failed on a different test run instead, if you want.)
- show_test_results takes one argument, the name of a test run (e.g., 'testrun-0007') or just 'latest'. It dumps out to your screen a very nice analysis of exactly what failed in that test run, and why. (This is the same analysis you get at the end of the test run itself, in fact.)
Testing in Eclipse or Other Tools
- check_show takes two arguments, a module name and a test type. (For example, 'tcbuild check_show legacy-test-tree unit'.) It will do absolutely all work that the buildsystem does to prepare for running tests on a particular subtree - things like building boot JARs, creating appropriate test-data directories, and so on - and then prints to the screen all the properties it will set, CLASSPATH it will use, current working directory it will use, and so on. This can be used to figure out how to run tests in any arbitrary tool, since it shows you all the settings you need.
- check_prep works exactly like check_show, except that it ~also~ drops a file on your CLASSPATH (more precisely, in build/simulator/src.classes, though this may change at any time) that specifies some system properties. The test code (specifically, TestConfigObject) looks for this file and sets these system properties. As such, you can use this to run tests in Eclipse: just run 'tcbuild check_prep <modulename> <test-type>' first, and then run your tests in Eclipse - no other work needed. Note that this is the ONLY supported way of doing this from Eclipse; it ensures that everything stays maintainable into the future, among other things.
(Also note that certain test trees are configured to, for example, run with a DSO boot JAR active; 'check_show' and 'check_prep' will tell you about this, and tell you how to configure Eclipse so that it behaves identically to the buildsystem, but they can't actually do it themselves since Eclipse kicks off the test JVM itself, before our code has any control. Some tests may run fine anyway, but, for others, you may need to change Eclipse's idea of the JVM arguments and other options it should use when kicking off that test.)
Running Servers, Classes, etc.
- run_class takes at least one argument - the name of a class to run. Any further arguments are passed to that class. (Currently, this class name must be fully-qualified, although this may change in the future to make things easier). You can also specify the following properties (name=value pairs on the command line):
- module: Sets the module to run against (for the CLASSPATH, JVM version, and so on). Defaults to 'legacy-test-tree'.
- subtree: Sets the subtree to run against (for the CLASSPATH, native libraries, and so on). Defaults to 'src'.
- jvm: Sets the JVM to run against; this can be '1.4', '1.5', or a fully-qualified path to a valid Java home.
- jvmargs: Sets the JVM arguments to use; this should be a comma-separated list. Defaults to no extra JVM arguments.
- with_dso: if you set this to 'true', the process will get DSOized - a boot JAR will get built for it, a Terracotta home set up (a license file and 'tc-config.xml' file put there), 'tc.config' set to point to the config file, and 'tc.classpath' set to point to the appropriate classes. You can actually override any of these things by simply adding the appropriate arguments to 'jvmargs'; for example, if you define a JVM argument that looks like '-Xbootclasspath...', we won't add a second one pointing to the boot JAR. In this way you can pretty much do anything you want. (If you want to change the boot JAR, just run this once, then edit the tc-config.xml file appropriately, then run it again. The boot JAR will pick up the changes the second time around.)
- run_server runs the Terracotta server. The 'jvmargs' parameter can be used to set JVM arguments for it, if you need any extra ones.
Miscellaneous
- show_classpath takes two arguments - the name of the module and the name of a subtree. (For example, 'tcbuild show_classpath common test.unit'.) This prints to your screen the CLASSPATH that gets used when you run code against that tree. This can be useful for running classes or other tools outside of Eclipse or the buildsystem itself.
- create_boot_jar takes one argument - the type of JVM to create a boot JAR for. This can be '1.4', '1.5', or the fully-qualified path to a Java home. It will create a boot JAR for this JVM, and tell you where it left it.
- show_config dumps out the various configuration parameters that the build system itself is building with.
|
