harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From smish...@apache.org
Subject svn commit: r551447 - /harmony/enhanced/buildtest/branches/2.0/README.txt
Date Thu, 28 Jun 2007 05:05:09 GMT
Author: smishura
Date: Wed Jun 27 22:05:08 2007
New Revision: 551447

URL: http://svn.apache.org/viewvc?view=rev&rev=551447
Update README.txt by its new version from HARMONY-4293:([testing] documentation for BTI is


Modified: harmony/enhanced/buildtest/branches/2.0/README.txt
URL: http://svn.apache.org/viewvc/harmony/enhanced/buildtest/branches/2.0/README.txt?view=diff&rev=551447&r1=551446&r2=551447
--- harmony/enhanced/buildtest/branches/2.0/README.txt (original)
+++ harmony/enhanced/buildtest/branches/2.0/README.txt Wed Jun 27 22:05:08 2007
@@ -1,221 +1,171 @@
-                           =========================
-                           Build Test Infrastructure
-                           =========================
+                    ========================================
+                    Harmony Build and Testing Infrastructure
+                    ========================================
+Harmony BTI is intended to organize overall project Build & Testing 
+activities in one place. This infrastructure provides the means to:
+    - configure and launch test runs on the base of integrated test suites,
+    - implement and integrate new test suites,
+    - organize automated builds and code integrity checking processes
-Archive Content
-This archive contains improved and restructured Build Test (BT) Infrastructure.
-New BT architecture brings the clear structure on the trunk as well as several
-useful means simplifying test suite execution and new test suite integration.
-  +/
-   |-+scripts/      - BT Framework Implementation
-   |
-   |-+adaptors/     - Adaptors connecting test suites to BT
-   |
-   |-+tests/        - Tests suites placed under BuildTest repository
-   |
-   |-build.xml      - Main Build File
-   |
-   |-buildtest.dtd  - DTD for Main Build File
-   |
-   |-README.txt     - Readme File
-   |
-   |-SPEC.txt       - BT Specification
-Pre-requisites for BT Use
-To use BT following tools are required to be preinstalled on your system:
+To get HY BTI working on your system, you should have the following tools
-  1) JDK version 1.5.0
+  1) JDK version 1.5.0:
-  2) Apache Ant, version 1.6 or higher 
+  2) Apache Ant, version 1.6.5
-  3) C compiler, either gcc for Linux*, or one of the following for Windows*:
-         + Microsoft* 32-bit C/C++ Compiler v.7 or higher,
-         + Windows* platform SDK,
-         + Microsoft* Visual Studio .NET* 2003 or higher
-           http://www.microsoft.com/downloads/
-  4) Subversion tool (svn)
-     http://subversion.tigris.org/
-Using BT Infrastructure
-Assumed BT usage (not actual, but after integration into repository, see next
-section for current use) is as follows:
-  ---------------------------------------
-* Test Execution (post integration vision)
-  ----------------------------------------
-  To launch some of the integrated test suites user should perform following 
-  1. Getting BT Infra
-      #> svn co -r HEAD -N http://svn.apache.org/repos/asf/harmony/enhanced/buildtest/trunk
-     It will download ONLY Main Build file and README's from SVN repository
-     Such a trick is needed for traffic and checkout time economy.
-  2. Setting Up and getting needed Test Suites:
-    #> buildtest -Dtest.suites="classlib,drlvm" setup
-    It will:
-      1. Download BT Framework implementation (./scripts dir from BT trunk) if
-         it has not been done yet.
-      2. Set Up the Framework
-      3. Download adaptors for classlib and drlvm test suites already 
-         integrated into BT (if it has not been done yet).
-      4. Launch Set Up for selected Test Suites. These Set Ups will download
-         (or update) needed test sources for selected Test Suites and prepare
-         them for execution.
-      5. Extract REQUIRED parameters needed to be specified by used and
-         request user to provide the values for them.
+  3) Subversion tool (svn)
+     http://subversion.tigris.org/
-  3. User provides REQUIRED values for the build configuration
+Some of the test suites (involving CLASSLIB or DRLVM builds) 
+need C compiler. It can be either:
+    - gcc for Linux*, or 
+    - Microsoft* Visual Studio .NET* 2003 for Windows*
-  4. Execution of selected test suites:
-    #> buildtest
-      or 
-    #> buildtest run
+Getting started
-  5. Execution under Cruise Control system:
+To get started with HY BTI go through the points below. For quick start you
+can skip long explanations - just read the headers of the items and execute
+the commands started with #>
-    #> buildtest cc-run
+1. Get the infrastructure from its SVN repository (located at @LINK): 
-  ------------------------------------
-* Test Execution (pre-integration use)
-  ------------------------------------
+    #> svn checkout -N -r HEAD @LINK
-As it is not under SVN yet, to run the suites user should perform the following
+Currently the link for HY BTI SVN repository is:
+    https://svn.apache.org/repos/asf/harmony/enhanced/buildtest/branches/2.0
-  1. Setting Up and getting needed Test Suites:
-    #> buildtest.bat -Dtest.suites="classlib,drlvm" setup
+It is important to use https protocol on this step: If you're running BTI on 
+your workstation for a first time, this command will initially download 
+SSL certificate from repository hosting site and ask for acceptance.
+To proceed you should accept the certificate permanently.
-  2. User provides REQUIRED values for the build configuration
-  3. Run the suites:
+2. Install the BTI: Tune environment variables in buildtest scripts 
+downloaded during the first step. And run the following command:
+    #> buildtest install
-    #> buildtest.bat -Dtest.suites="classlib,drlvm" run
-     or under CC:
-    #> buildtest.bat -Dtest.suites="classlib,drlvm" run-cc
-New Test Suite Integration
-To Integrate your Test Suite (say, 'my-test-suite') into new BT Framework you
-should perform the following steps:
-   1. Implement Adaptor interface for your Test Suite:
-     : implement _setup_, _run_, _clean_ targets in 
-          ${root.dir}/my-test-suite/adaptor.xml
-     * More on _Adaptors_ see at "SPEC.txt/Test Suite Adaptors" section
-   2. Define the Parameters of the Test Suite in 
-          ${root.dir}/my-test-suite/parameters.xml 
-      file:
-       - <required> section - list all properties required to be set up by user
-       - <shared> section - list all the values to be shared by the test suite
-       - <external> section - list all external dependencies to be downloaded
-       - <optional> section - list optional parameters for low-level tuning (not
-         supported at this development stage)
-       - depends attribute - coma separated list of dependencies on other suites
-     * More on _Parameters_ see at "SPEC.txt/Test Suite Parameters" section
-   3. Place adaptor.xml and parameters.xml under adaptor/${suite.name}
-      directory
-   4. If there is a reason to place sources of new Test Suite under BT
-      SVN, place them under tests/${suite.name} directory of BT repository and
-      use this location as a pointer to the sources.
-      -----
-      Note: Assumed BT usage does not suppose that all of the BT trunk files
-      ----- will be checked out. So adaptor.xml should check out the sources
-            by itself.
-   5. To run your 'my-test-suite' suite alone:
-      1. Set up environment variables in buildtest.bat
-      2. If you're using proxy for internet connection, set it up at ANT_OPTS
-         variable.
-      3. Type:
-            #> buildtest.bat -Dtest.suites=my-test-suite setup
-         to setup BT Infra.
-      4. Specify all of the required parameters in generated
-            required-parameters.properties
-         file.
-      5. Type:
-            #> buildtest.bat -Dtest.suites=my-test-suite run
-         to execute your suite alone.
-      6. Type:
-            #> buildtest.bat -Dtest.suites=my-test-suite run-cc
-         to launch continuous execution of your test suite.
-   6. Do 5. without
-        -Dtest.suites=my-test-suite
-      parameter to setup and execute all of the installed test suites.
-Active Workspace Structure
-  +/
-   |-+build/
-   |  |
-   |  |-+cc/        - CC related stuff
-   |  |
-   |  |-+checkouts/ - externally checkouted test suites (not included in BUILDTEST)
-   |  |
-   |  |-+lib/       - external libraries needed for fwk and test suites
-   |  |
-   |  |-+tmp/       - temporary files
-   |
-   |
-   |-+scripts/      - Framework implementation
-   |
-   |-+adaptors/     - Test Suites adaptors implementations
-   |
-   |-+tests/        - Tests Suites placed under BUILDTEST and dowlnoaded on 'setup' stage
-   |
-   |-build.xml      - Main Build file
-   |
-   |-buildtest.dtd  - DTD for Main Build File
-   |
-   |-README.txt     - Readme file
-   |
-   |-SPEC.txt       - BT Specification
+3. Select test suites to execute and setup your test run configuration:
+    #> buildtest -Dtest.suites="classlib,drlvm,scimark" setup
+This sample configuration means: execute classlib building (test that it can
+be built), then on the base of built classlib do build of drlvm (test that it
+also can be built), and after that run the SciMark benchmark on the product of
+drlvm test suite (which is built JVM).
+Such a meaning is reached by the following information provided by test
+suites: information about dependencies between the suites, and information
+about the product provided by one suite to another. This information is
+described in parameters.xml file placed under 'adaptors' dir for each of test
+suites. This file is an Ant xml property file and having some semantics defined
+on each of the properties. 
+So the property 'depends' defined in parameters.xml file lists the test
+suites on which this test suite depends in default configuration. For example
+look in adaptors/scimark/parameters.xml file: by default the scimark test
+suite depends on drlvm: if drlvm and scimark are selected for test run
+together, then scimark is always executed after drlvm and it takes JVM
+provided by drlvm as JVM to test. If drlvm test suite was not selected for
+run, then scimark's 'tested.runtime' "required" parameter won't be resolved
+and BTI will ask to provide this value by means of
+required-parameters.properties file. 
+drlvm test suite provides information about built JVM to other test suites
+by means of "shared" 'jvm.location' parameter. 
+To get this value scimark test suite in its parameters.xml file
+makes assignment of its "required" parameter 'tested.runtime' to drlvm's
+"shared" parameter 'jvm.location'.
+That's the base means used to describe the execution order of the test suites
+and the values of required parameters needed for test suite execution.
+The command line above complies with default configuration expected by selected
+test suites. But what if it does not? What if we chose the following
+configuration to be executed: -Dtest.suites="hdk,scimark" (do build HDK and
+execute SciMark on top of it). In this case we need to change scimark's
+dependency information and the information from where to get the JVM to test.
+It is done by means of the following properties specified in
+framework.local.properties file before 'buildtest setup' execution:
+  - tells to BTI to execute scimark after hdk
+  - tells to BTI where to take JVM for scimark
+These properties redefines the parameters defined in scimark's 
+parameters.xml file.
+That's all about dependencies between the test suites.
+'buildtest setup' command generates required-parameters.properties file. 
+It contains all of the assignments of "required" parameters. 
+If some of the "required" parameters were not evaluated, 
+BTI will report an ERROR and demand to specify the values for
+unspecified parameters. You should whether provide them directly in 
+required-parameters.properties file (this way is better for some predefined 
+values, hardcoded path to tested JVM for example) and go to next step, 
+or provide "required" to "shared" correspondence (as above) in 
+framework.local.properties file and repeat 'buildtest setup'. 
+Note: the values provided in required-parameters.properties take precedence
+over the values provided in parameters.xml or framework.local.properties
+files. So, if you change the values of required parameters in parameters.xml,
+or in framework.local.properties file, you should delete corresponding
+required parameter from required-parameters.properties file.
+For example of usage of the required-parameters.properties file let's look at
+the configuration containing only scimark test suite:
+'buildtest -Dtest.suite=scimark setup' command will end with demand to specify 
+the value for 'scimark.tested.runtime' "required" parameter. We just write the
+following line in required-parameters.properties file:
+and go to the next point of the usage guide.
+4. To launch the configured test run, type the following:
+    #> buildtest run
+It will execute selected test suites. BTI will execute each of the suites and
+report SUCCESS if there were no test failures and ERROR otherwise.
+To launch continuous test run, type the following:
+    #> buildtest run-cc
+It will launch CC controlled continuous test execution. There are two modes of
+continuous execution: SVN modifications triggered and scheduled runs. SVN
+modifications triggered runs are executed each time SVN modification occurs.
+The SVN repositories controlled by test suites are defined by cc.usesvn*
+properties defined in parameters.xml file. For example look in the parameters
+for classlib or hdk test suites. Scheduled runs are launched at the particular
+time specified by the following properties in framework.local.properties file:
+ - Do launch test suites execution on particular day. 
+   If this property is not defined, the test run will be launched everyday.
+ - Do launch test suites execution at this particular time.
+   Should be defined for scheduled execution mode.
+*) Other brands and names are the property of their respective owners

View raw message