doc/overview/customizing.html

   1 <HTML
   2 ><HEAD
   3 ><TITLE
   4 >Customizing DejaGnu</TITLE
   5 ><META
   6 NAME="GENERATOR"
   7 CONTENT="Modular DocBook HTML Stylesheet Version 1.44"><LINK
   8 REL="HOME"
   9 TITLE="DejaGnu"
  10 HREF="book1.html"><LINK
  11 REL="PREVIOUS"
  12 TITLE="The files DejaGnu produces."
  13 HREF="outputfiles.html"><LINK
  14 REL="NEXT"
  15 TITLE="Global Config File"
  16 HREF="global.html"></HEAD
  17 ><BODY
  18 ><DIV
  19 CLASS="NAVHEADER"
  20 ><TABLE
  21 WIDTH="100%"
  22 BORDER="0"
  23 CELLPADDING="0"
  24 CELLSPACING="0"
  25 ><TR
  26 ><TH
  27 COLSPAN="3"
  28 ALIGN="center"
  29 >DejaGnu: The GNU Testing Framework</TH
  30 ></TR
  31 ><TR
  32 ><TD
  33 WIDTH="10%"
  34 ALIGN="left"
  35 VALIGN="bottom"
  36 ><A
  37 HREF="outputfiles.html"
  38 >Prev</A
  39 ></TD
  40 ><TD
  41 WIDTH="80%"
  42 ALIGN="center"
  43 VALIGN="bottom"
  44 ></TD
  45 ><TD
  46 WIDTH="10%"
  47 ALIGN="right"
  48 VALIGN="bottom"
  49 ><A
  50 HREF="global.html"
  51 >Next</A
  52 ></TD
  53 ></TR
  54 ></TABLE
  55 ><HR
  56 ALIGN="LEFT"
  57 WIDTH="100%"></DIV
  58 ><DIV
  59 CLASS="CHAPTER"
  60 ><H1
  61 ><A
  62 NAME="CUSTOMIZING"
  63 >Chapter 3. Customizing DejaGnu</A
  64 ></H1
  65 ><DIV
  66 CLASS="TOC"
  67 ><DL
  68 ><DT
  69 ><B
  70 >Table of Contents</B
  71 ></DT
  72 ><DT
  73 ><A
  74 HREF="customizing.html#LOCAL"
  75 >Local Config File</A
  76 ></DT
  77 ><DT
  78 ><A
  79 HREF="global.html"
  80 >Global Config File</A
  81 ></DT
  82 ><DT
  83 ><A
  84 HREF="boardconfig.html"
  85 >Board Config File</A
  86 ></DT
  87 ><DT
  88 ><A
  89 HREF="releng.html"
  90 >Remote Host Testing</A
  91 ></DT
  92 ><DT
  93 ><A
  94 HREF="configfile.html"
  95 >Config File Values</A
  96 ></DT
  97 ></DL
  98 ></DIV
  99 ><P
 100 >The site configuration file, <TT
 101 CLASS="FILENAME"
 102 >site.exp</TT
 103 >,
 104     captures configuration-dependent values and propagates them to the
 105     DejaGnu test environment using Tcl variables.  This ties the
 106     DejaGnu test scripts into the <B
 107 CLASS="COMMAND"
 108 >configure</B
 109 > and
 110     <B
 111 CLASS="COMMAND"
 112 >make</B
 113 > programs. If this file is setup correctly,
 114     it is possible to execute a test suite merely by typing
 115     <B
 116 CLASS="COMMAND"
 117 >runtest</B
 118 >.</P
 119 ><P
 120 >DejaGnu supports two <TT
 121 CLASS="FILENAME"
 122 >site.exp</TT
 123 >
 124     files. The multiple instances of <TT
 125 CLASS="FILENAME"
 126 >site.exp</TT
 127 > are
 128     loaded in a fixed order built into DejaGnu. The first file loaded
 129     is the local file <TT
 130 CLASS="FILENAME"
 131 >site.exp</TT
 132 >, and then the
 133     optional global <TT
 134 CLASS="FILENAME"
 135 >site.exp</TT
 136 > file as
 137     pointed to by the <SPAN
 138 CLASS="SYMBOL"
 139 >DEJAGNU</SPAN
 140 > environment
 141     variable.</P
 142 ><P
 143 >There is an optional <I
 144 CLASS="EMPHASIS"
 145 >master</I
 146 >
 147     <TT
 148 CLASS="FILENAME"
 149 >site.exp</TT
 150 >, capturing configuration values that
 151     apply to DejaGnu across the board, in each configuration-specific
 152     subdirectory of the DejaGnu library directory.
 153     <B
 154 CLASS="COMMAND"
 155 >runtest</B
 156 > loads these values first. The master
 157     <TT
 158 CLASS="FILENAME"
 159 >site.exp</TT
 160 > contains the default values for all
 161     targets and hosts supported by DejaGnu. This master file is
 162     identified by setting the environment variable
 163     <SPAN
 164 CLASS="SYMBOL"
 165 >DEJAGNU</SPAN
 166 > to the name of the file. This is also
 167     refered to as the ``global'' config file.</P
 168 ><P
 169 >Any directory containing a configured test suite also has a
 170     local <TT
 171 CLASS="FILENAME"
 172 >site.exp</TT
 173 >, capturing configuration values
 174     specific to the tool under test.  Since <B
 175 CLASS="COMMAND"
 176 >runtest</B
 177 >
 178     loads these values last, the individual test configuration can
 179     either rely on and use, or override, any of the global values from
 180     the global <TT
 181 CLASS="FILENAME"
 182 >site.exp</TT
 183 > file.</P
 184 ><P
 185 >You can usually generate or update the testsuite's local
 186     <TT
 187 CLASS="FILENAME"
 188 >site.exp</TT
 189 > by typing <B
 190 CLASS="COMMAND"
 191 >make
 192     site.exp</B
 193 > in the test suite directory, after the test
 194     suite is configured.</P
 195 ><P
 196 >You can also have a file in your home directory called
 197     <TT
 198 CLASS="FILENAME"
 199 >.dejagnurc</TT
 200 >. This gets loaded first before the
 201     other config files. Usually this is used for personal stuff, like
 202     setting the <SPAN
 203 CLASS="SYMBOL"
 204 >all_flag</SPAN
 205 > so all the output gets
 206     printed, or your own verbosity levels. This file is usually
 207     restricted to setting command line options.</P
 208 ><P
 209 >You can further override the default values in a
 210     user-editable section of any <TT
 211 CLASS="FILENAME"
 212 >site.exp</TT
 213 >, or by
 214     setting variables on the <B
 215 CLASS="COMMAND"
 216 >runtest</B
 217 > command
 218     line.</P
 219 ><DIV
 220 CLASS="SECT1"
 221 ><H1
 222 CLASS="SECT1"
 223 ><A
 224 NAME="LOCAL"
 225 >Local Config File</A
 226 ></H1
 227 ><P
 228 >It is usually more convenient to keep these <I
 229 CLASS="EMPHASIS"
 230 >manual
 231       overrides</I
 232 > in the <TT
 233 CLASS="FILENAME"
 234 >site.exp</TT
 235 >
 236       local to each test directory, rather than in the global
 237       <TT
 238 CLASS="FILENAME"
 239 >site.exp</TT
 240 > in the installed DejaGnu
 241       library. This file is mostly for supplying tool specific info
 242       that is required by the test suite.</P
 243 ><P
 244 >All local <TT
 245 CLASS="FILENAME"
 246 >site.exp</TT
 247 > files have
 248       two sections, separated by comment text. The first section is
 249       the part that is generated by <B
 250 CLASS="COMMAND"
 251 >make</B
 252 >. It is
 253       essentially a collection of Tcl variable definitions based on
 254       <TT
 255 CLASS="FILENAME"
 256 >Makefile</TT
 257 > environment variables. Since they
 258       are generated by <B
 259 CLASS="COMMAND"
 260 >make</B
 261 >, they contain the
 262       values as specified by <B
 263 CLASS="COMMAND"
 264 >configure</B
 265 >.  (You can
 266       also customize these values by using the <TT
 267 CLASS="OPTION"
 268 >--site</TT
 269 >
 270       option to <B
 271 CLASS="COMMAND"
 272 >configure</B
 273 >.) In particular, this
 274       section contains the <TT
 275 CLASS="FILENAME"
 276 >Makefile</TT
 277 >
 278       variables for host and target configuration data. Do not edit
 279       this first section; if you do, your changes are replaced next
 280       time you run <B
 281 CLASS="COMMAND"
 282 >make</B
 283 >.</P
 284 ><DIV
 285 CLASS="EXAMPLE"
 286 ><P
 287 ><B
 288 >Example 3-1. The first section starts with</B
 289 ></P
 290 ><TABLE
 291 BORDER="0"
 292 BGCOLOR="#E0E0E0"
 293 WIDTH="100%"
 294 ><TR
 295 ><TD
 296 ><PRE
 297 CLASS="PROGRAMLISTING"
 298 >       ## these variables are automatically generated by make ##
 299         # Do not edit here. If you wish to override these values
 300         # add them to the last section
 301         </PRE
 302 ></TD
 303 ></TR
 304 ></TABLE
 305 ></DIV
 306 ><P
 307 >In the second section, you can override any default values
 308       (locally to DejaGnu) for all the variables.  The second section
 309       can also contain your preferred defaults for all the command
 310       line options to <B
 311 CLASS="COMMAND"
 312 >runtest</B
 313 >. This allows you to
 314       easily customize <B
 315 CLASS="COMMAND"
 316 >runtest</B
 317 > for your preferences
 318       in each configured test-suite tree, so that you need not type
 319       options repeatedly on the command line.  (The second section may
 320       also be empty, if you do not wish to override any defaults.)</P
 321 ><DIV
 322 CLASS="EXAMPLE"
 323 ><P
 324 ><B
 325 >Example 3-2. The first section ends with this line</B
 326 ></P
 327 ><TABLE
 328 BORDER="0"
 329 BGCOLOR="#E0E0E0"
 330 WIDTH="100%"
 331 ><TR
 332 ><TD
 333 ><PRE
 334 CLASS="PROGRAMLISTING"
 335 >       ## All variables above are generated by configure. Do Not Edit ##
 336         </PRE
 337 ></TD
 338 ></TR
 339 ></TABLE
 340 ></DIV
 341 ><P
 342 >You can make any changes under this line. If you wish to
 343       redefine a variable in the top section, then just put a
 344       duplicate value in this second section. Usually the values
 345       defined in this config file are related to the configuration of
 346       the test run. This is the ideal place to set the variables
 347       <SPAN
 348 CLASS="SYMBOL"
 349 >host_triplet</SPAN
 350 >, <SPAN
 351 CLASS="SYMBOL"
 352 >build_triplet</SPAN
 353 >,
 354       <SPAN
 355 CLASS="SYMBOL"
 356 >target_triplet</SPAN
 357 >. All other variables are tool
 358       dependant. ie for testing a compiler, the value for
 359       <SPAN
 360 CLASS="SYMBOL"
 361 >CC</SPAN
 362 > might be set to a freshly built binary, as
 363       opposed to one in the user's path.</P
 364 ><P
 365 >Here's an example local site.exp file, as used for
 366       <SPAN
 367 CLASS="PRODUCTNAME"
 368 >GCC/G++</SPAN
 369 > testing.</P
 370 ><DIV
 371 CLASS="EXAMPLE"
 372 ><P
 373 ><B
 374 >Example 3-3. Local Config File</B
 375 ></P
 376 ><TABLE
 377 BORDER="0"
 378 BGCOLOR="#E0E0E0"
 379 WIDTH="100%"
 380 ><TR
 381 ><TD
 382 ><PRE
 383 CLASS="PROGRAMLISTING"
 384 >
 385       ## these variables are automatically generated by make ##
 386       # Do not edit here. If you wish to override these values
 387       # add them to the last section
 388       set rootme "/build/devo-builds/i586-pc-linux-gnulibc1/gcc"
 389       set host_triplet i586-pc-linux-gnulibc1
 390       set build_triplet i586-pc-linux-gnulibc1
 391       set target_triplet i586-pc-linux-gnulibc1
 392       set target_alias i586-pc-linux-gnulibc1
 393       set CFLAGS ""
 394       set CXXFLAGS "-I/build/devo-builds/i586-pc-linux-gnulibc1/gcc/../libio -I$srcdir/../libg++/src -I$srcdir/../libio -I$srcdir/../libstdc++ -I$srcdir/../libstdc++/stl -L/build/devo-builds/i586-pc-linux-gnulibc1/gcc/../libg++ -L/build/devo-builds/i586-pc-linux-gnulibc1/gcc/../libstdc++"
 395       append LDFLAGS " -L/build/devo-builds/i586-pc-linux-gnulibc1/gcc/../ld"
 396       set tmpdir /build/devo-builds/i586-pc-linux-gnulibc1/gcc/testsuite
 397       set srcdir "${srcdir}/testsuite"
 398       ## All variables above are generated by configure. Do Not Edit ##
 399
 400       </PRE
 401 ></TD
 402 ></TR
 403 ></TABLE
 404 ></DIV
 405 ><P
 406 >This file defines the required fields for a local config
 407     file, namely the three config triplets, and the srcdir. It also
 408     defines several other Tcl variables that are used exclusivly by
 409     the GCC test suite. For most test cases, the CXXFLAGS and LDFLAGS
 410     are supplied by DejaGnu itself for cross testing, but to test a
 411     compiler, GCC needs to manipulate these itself.</P
 412 ></DIV
 413 ></DIV
 414 ><DIV
 415 CLASS="NAVFOOTER"
 416 ><HR
 417 ALIGN="LEFT"
 418 WIDTH="100%"><TABLE
 419 WIDTH="100%"
 420 BORDER="0"
 421 CELLPADDING="0"
 422 CELLSPACING="0"
 423 ><TR
 424 ><TD
 425 WIDTH="33%"
 426 ALIGN="left"
 427 VALIGN="top"
 428 ><A
 429 HREF="outputfiles.html"
 430 >Prev</A
 431 ></TD
 432 ><TD
 433 WIDTH="34%"
 434 ALIGN="center"
 435 VALIGN="top"
 436 ><A
 437 HREF="book1.html"
 438 >Home</A
 439 ></TD
 440 ><TD
 441 WIDTH="33%"
 442 ALIGN="right"
 443 VALIGN="top"
 444 ><A
 445 HREF="global.html"
 446 >Next</A
 447 ></TD
 448 ></TR
 449 ><TR
 450 ><TD
 451 WIDTH="33%"
 452 ALIGN="left"
 453 VALIGN="top"
 454 >The files DejaGnu produces.</TD
 455 ><TD
 456 WIDTH="34%"
 457 ALIGN="center"
 458 VALIGN="top"
 459 >&nbsp;</TD
 460 ><TD
 461 WIDTH="33%"
 462 ALIGN="right"
 463 VALIGN="top"
 464 >Global Config File</TD
 465 ></TR
 466 ></TABLE
 467 ></DIV
 468 ></BODY
 469 ></HTML
 470 >