doc/html/cdl-guide/build.tests.html

   1 <!-- Copyright (C) 2003 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >Building Test Cases</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="The eCos Component Writer's Guide"
  20 HREF="cdl-guide.html"><LINK
  21 REL="UP"
  22 TITLE="The Build Process"
  23 HREF="build.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="Building eCos"
  26 HREF="build.make.html"><LINK
  27 REL="NEXT"
  28 TITLE="CDL Language Specification"
  29 HREF="reference.html"></HEAD
  30 ><BODY
  31 CLASS="SECT1"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >The <SPAN
  50 CLASS="APPLICATION"
  51 >eCos</SPAN
  52 > Component Writer's Guide</TH
  53 ></TR
  54 ><TR
  55 ><TD
  56 WIDTH="10%"
  57 ALIGN="left"
  58 VALIGN="bottom"
  59 ><A
  60 HREF="build.make.html"
  61 ACCESSKEY="P"
  62 >Prev</A
  63 ></TD
  64 ><TD
  65 WIDTH="80%"
  66 ALIGN="center"
  67 VALIGN="bottom"
  68 >Chapter 4. The Build Process</TD
  69 ><TD
  70 WIDTH="10%"
  71 ALIGN="right"
  72 VALIGN="bottom"
  73 ><A
  74 HREF="reference.html"
  75 ACCESSKEY="N"
  76 >Next</A
  77 ></TD
  78 ></TR
  79 ></TABLE
  80 ><HR
  81 ALIGN="LEFT"
  82 WIDTH="100%"></DIV
  83 ><DIV
  84 CLASS="SECT1"
  85 ><H1
  86 CLASS="SECT1"
  87 ><A
  88 NAME="BUILD.TESTS">Building Test Cases</H1
  89 ><DIV
  90 CLASS="CAUTION"
  91 ><P
  92 ></P
  93 ><TABLE
  94 CLASS="CAUTION"
  95 BORDER="1"
  96 WIDTH="100%"
  97 ><TR
  98 ><TD
  99 ALIGN="CENTER"
 100 ><B
 101 >Caution</B
 102 ></TD
 103 ></TR
 104 ><TR
 105 ><TD
 106 ALIGN="LEFT"
 107 ><P
 108 >The support in the current implementation of the component framework
 109 for building and running test cases is limited, and should be enhanced
 110 considerably in a future version. Compatibility with the existing
 111 mechanisms described below will be maintained if possible, but this
 112 cannot be guaranteed.</P
 113 ></TD
 114 ></TR
 115 ></TABLE
 116 ></DIV
 117 ><P
 118 >Whenever possible packages should be shipped with one or more test
 119 cases. This allows users to check that all packages function correctly
 120 in their particular configuration and on their target, which may be
 121 custom hardware unavailable to the package developer. The component
 122 framework needs to provide a way of building such test cases. For
 123 example, if a makefile system is used then there could be a
 124 <TT
 125 CLASS="LITERAL"
 126 >make&nbsp;tests</TT
 127 > target to build the test cases, or
 128 possibly a <TT
 129 CLASS="LITERAL"
 130 >make&nbsp;check</TT
 131 > target to build and run
 132 the test cases and process all the results. Unfortunately there are
 133 various complications.</P
 134 ><P
 135 >Not every test case will be applicable to every configuration. For
 136 example if the user has disabled the C library's
 137 <TT
 138 CLASS="VARNAME"
 139 >CYGPKG_LIBC_STDIO</TT
 140 > component then there is no point
 141 in building or running any of the test cases for that component. This
 142 implies that test cases need to be associated with configuration
 143 options somehow. It is possible for the test case to use one or more
 144 <TT
 145 CLASS="LITERAL"
 146 >#ifdef</TT
 147 > statements to check whether or not it is
 148 applicable in the current configuration, and compile to a null program
 149 when not applicable. This is inefficient because the test case will
 150 still get built and possibly run, even though it will not provide any
 151 useful information.</P
 152 ><P
 153 >Many packages involve direct interaction with hardware, for example a
 154 serial line or an ethernet interface. In such cases it is only
 155 worthwhile building and running the test if there is suitable software
 156 running at the other end of the serial line or listening on the same
 157 ethernet segment, and that software would typically have to run on the
 158 host. Of course the serial line in question may be hooked up to a
 159 different piece of hardware which the application needs to talk to, so
 160 disconnecting it and then hooking it up to the host for running some
 161 tests may be undesirable. The decision as to whether or not to build
 162 the test depends not just on the eCos configuration but also on the
 163 hardware setup and the availability of suitable host software.</P
 164 ><P
 165 >There are different kinds of tests, and it is not always desirable to
 166 run all of them. For example a package may contain a number of stress
 167 tests intended to run for long periods of time, possibly days or
 168 longer. Such tests should certainly be distinguished somehow from
 169 ordinary test cases so that users will not run them accidentally and
 170 wonder how long they should wait for a <TT
 171 CLASS="LITERAL"
 172 >pass</TT
 173 > message
 174 before giving up. Stress tests may also have dependencies on the
 175 hardware configuration and on host software, for example a network
 176 stress test may require lots of ethernet packets.</P
 177 ><P
 178 >In the current implementation of the component framework these issues
 179 are not yet addressed. Instead there is only very limited support for
 180 building test cases. Any package can define a calculated configuration
 181 option of the form
 182 <TT
 183 CLASS="LITERAL"
 184 >CYGPKG_&lt;package-name&gt;_TESTS</TT
 185 >, whose value is a
 186 list of test cases. The <SPAN
 187 CLASS="PROPERTY"
 188 >calculated</SPAN
 189 > property can involve an
 190 expression so it is possible to adapt to a small number of
 191 configuration options, but this quickly becomes unwieldy. A typical
 192 example would be:</P
 193 ><TABLE
 194 BORDER="5"
 195 BGCOLOR="#E0E0F0"
 196 WIDTH="70%"
 197 ><TR
 198 ><TD
 199 ><PRE
 200 CLASS="PROGRAMLISTING"
 201 >        cdl_option CYGPKG_UITRON_TESTS {
 202             display "uITRON tests"
 203             flavor  data
 204             no_define
 205             calculated { "tests/test1 tests/test2 tests/test3 \
 206                 tests/test4 tests/test5 tests/test6 tests/test7 \
 207                 tests/test8 tests/test9 tests/testcxx tests/testcx2 \
 208                 tests/testcx3 tests/testcx4 tests/testcx5 \
 209                 tests/testcx6 tests/testcx7 tests/testcx8 \
 210                 tests/testcx9 tests/testintr" }
 211             description   "
 212 This option specifies the set of tests for the uITRON compatibility layer."
 213         }</PRE
 214 ></TD
 215 ></TR
 216 ></TABLE
 217 ><P
 218 >This implies that there is a file <TT
 219 CLASS="FILENAME"
 220 >tests/test1.c</TT
 221 >
 222 or <TT
 223 CLASS="FILENAME"
 224 >tests/test1.cxx</TT
 225 > in the package's directory.
 226 The commands that will be used to build the test case will take the
 227 form:</P
 228 ><TABLE
 229 BORDER="5"
 230 BGCOLOR="#E0E0F0"
 231 WIDTH="70%"
 232 ><TR
 233 ><TD
 234 ><PRE
 235 CLASS="PROGRAMLISTING"
 236 >    $(CC) -c $(INCLUDE_PATH) $(CFLAGS) -o &lt;build path&gt;/test1.o \
 237          &lt;source path&gt;/tests/test1.c
 238     $(CC) $(LDFLAGS) -o &lt;install path&gt;/tests/test1 &lt;build_path&gt;/test1.o</PRE
 239 ></TD
 240 ></TR
 241 ></TABLE
 242 ><P
 243 >The variables <TT
 244 CLASS="LITERAL"
 245 >$(CC)</TT
 246 > and so on are determined in the
 247 same way as for custom build steps. The various paths and the current
 248 directory will depend on the exact build system being used, and are
 249 subject to change. As usual the sources in the component repository
 250 are treated as a read-only resources, intermediate files live in the
 251 build tree, and the desired executables should end up in the install
 252 tree. </P
 253 ><P
 254 >Each test source file must be self-contained. It is not possible at
 255 present to build a little per-package library that can be used by the
 256 test cases, or to link together several object files to produce a
 257 single test executable. In some cases it may be possible to
 258 <TT
 259 CLASS="LITERAL"
 260 >#include</TT
 261 > source code from a shared file in order to
 262 avoid unnecessary code replication. There is no support for
 263 manipulating compiler or linker flags for individual test cases: the
 264 flags that will be used for all files are <TT
 265 CLASS="LITERAL"
 266 >$(CFLAGS)</TT
 267 >
 268 and <TT
 269 CLASS="LITERAL"
 270 >$(LDFLAGS)</TT
 271 >, as per custom build steps. Note
 272 that it is possible for a package to define options of the form
 273 <TT
 274 CLASS="VARNAME"
 275 >CYGPKG_&lt;PACKAGE-NAME&gt;_LDFLAGS_ADD</TT
 276 > and
 277 <TT
 278 CLASS="VARNAME"
 279 >CYGPKG_&lt;PACKAGE-NAME&gt;_LDFLAGS_REMOVE</TT
 280 >. These
 281 will affect test cases, but in the absence of custom build steps they
 282 will have no other effect on the build.</P
 283 ></DIV
 284 ><DIV
 285 CLASS="NAVFOOTER"
 286 ><HR
 287 ALIGN="LEFT"
 288 WIDTH="100%"><TABLE
 289 SUMMARY="Footer navigation table"
 290 WIDTH="100%"
 291 BORDER="0"
 292 CELLPADDING="0"
 293 CELLSPACING="0"
 294 ><TR
 295 ><TD
 296 WIDTH="33%"
 297 ALIGN="left"
 298 VALIGN="top"
 299 ><A
 300 HREF="build.make.html"
 301 ACCESSKEY="P"
 302 >Prev</A
 303 ></TD
 304 ><TD
 305 WIDTH="34%"
 306 ALIGN="center"
 307 VALIGN="top"
 308 ><A
 309 HREF="cdl-guide.html"
 310 ACCESSKEY="H"
 311 >Home</A
 312 ></TD
 313 ><TD
 314 WIDTH="33%"
 315 ALIGN="right"
 316 VALIGN="top"
 317 ><A
 318 HREF="reference.html"
 319 ACCESSKEY="N"
 320 >Next</A
 321 ></TD
 322 ></TR
 323 ><TR
 324 ><TD
 325 WIDTH="33%"
 326 ALIGN="left"
 327 VALIGN="top"
 328 >Building eCos</TD
 329 ><TD
 330 WIDTH="34%"
 331 ALIGN="center"
 332 VALIGN="top"
 333 ><A
 334 HREF="build.html"
 335 ACCESSKEY="U"
 336 >Up</A
 337 ></TD
 338 ><TD
 339 WIDTH="33%"
 340 ALIGN="right"
 341 VALIGN="top"
 342 >CDL Language Specification</TD
 343 ></TR
 344 ></TABLE
 345 ></DIV
 346 ></BODY
 347 ></HTML
 348 >