www/lit_usage.html - platform/external/libcxx - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
           "http://www.w3.org/TR/html4/strict.dtd">
 <!-- Material used from: HTML 4.01 specs: http://www.w3.org/TR/html401/ -->
 <html>
 <head>
   <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   <title>Testing libc++ using LIT</title>
   <link type="text/css" rel="stylesheet" href="menu.css">
   <link type="text/css" rel="stylesheet" href="content.css">
   <style>
     .lit-option {
       padding-top: 0.5em;
       margin-bottom: 0.0em;
       font-size: medium;
       color: #2d58b7
     }
     .lit-option-desc {
       display: block;
       margin-top: 0em;
       margin-bottom: 0em;
       margin-left: 20px;
       margin-right: 20px;
     }
   </style>
 </head>

 <body>
 <div id="menu">
   <div>
     <a href="http://llvm.org/">LLVM Home</a>
   </div>

   <div class="submenu">
     <label>libc++ Info</label>
     <a href="/index.html">About</a>
   </div>

   <div class="submenu">
     <label>Quick Links</label>
     <a href="http://lists.llvm.org/mailman/listinfo/cfe-dev">cfe-dev</a>
     <a href="http://lists.llvm.org/mailman/listinfo/cfe-commits">cfe-commits</a>
     <a href="http://llvm.org/bugs/">Bug Reports</a>
     <a href="http://llvm.org/svn/llvm-project/libcxx/trunk/">Browse SVN</a>
     <a href="http://llvm.org/viewvc/llvm-project/libcxx/trunk/">Browse ViewVC</a>
   </div>
 </div>

 <div id="content">
 <!--*********************************************************************-->
                      <h1>Testing libc++ using LIT</h1>
 <!--*********************************************************************-->
 <p>
 libc++ uses LIT to configure and run its tests. The primary way to run the
 libc++ tests is by using <code>make check-libcxx</code>. However since libc++
 can be used in any number of possible configurations it is important to
 customize the way LIT builds and runs the tests. This guide provides
 information on how to use LIT directly to test libc++.
 </p>
 <p>
 Documentation for LIT can be found
 <a href="http://llvm.org/docs/CommandGuide/lit.html">here</a>.
 </p>

 <!--*********************************************************************-->
                         <h2>Getting Started</h2>
 <!--*********************************************************************-->
 <p>
 After building libc++ use the following commands before you start using LIT to
 test.
 </p>
 <ul>
   <li><code>alias lit='python path/to/llvm/utils/lit/lit.py'</code></li>
   <li><code>export LIBCXX_SITE_CONFIG=path/to/build-libcxx/test/lit.site.cfg</code></li>
 </ul>
 <p>
 You can now run the libc++ tests by running:
 </p>
 <ul>
   <li><code>cd path/to/libcxx</code></li>
   <li><code>lit -sv ./test</code></li>
 </ul>
 <p>
 To only run a subsection of the tests use:
 <ul>
   <li><code>lit -sv test/std/numerics # Run only the numeric tests</code></li>
 </ul>

 <!--*********************************************************************-->
                      <h2>Customization Options</h2>
 <!--*********************************************************************-->
 <p>
 libc++'s testsuite provides multiple options to configure the way the tests
 are build and run. To use these options you pass them on the LIT command line
 as <code>--param NAME</code> or <code>--param NAME=VALUE</code>. Some options
 have default values specified during CMake's configuration. Passing the option
 on the command line will override the default.
 </p>


 <p>
 <h3 class="lit-option">libcxx_site_config=&lt;path/to/lit.site.cfg&gt;</h3>
 <blockquote class="lit-option-desc">
 Specify the site configuration to use when running the tests. This option
 overrides the enviroment variable <code>LIBCXX_SITE_CONFIG</code>
 </blockquote>
 </p>

 <p>
 <h3 class="lit-option">libcxx_headers=&lt;path/to/headers&gt;</h3>
 <blockquote class="lit-option-desc">
 Specify the libc++ headers that are tested. By default the headers in the source
 tree are used.
 </blockquote>
 </p>

 <p>
 <h3 class="lit-option">libcxx_library=&lt;path/to/libc++.so&gt;</h3>
 <blockquote class="lit-option-desc">
 Specify the libc++ library that is tested. By default the library in the build
 directory is used. This option cannot be used when <code>use_system_lib</code>
 is provided.
 </blockquote>
 </p>

 <p>
 <h3 class="lit-option">use_system_lib=&lt;bool&gt;</h3>
 <blockquote class="lit-option-desc">
 <b>Default: </b><code>False</code></br>
 Enable or disable testing against the installed version of libc++ library.
 Note: This does not use the installed headers.
 </blockquote>
 </p>

 <p>
 <h3 class="lit-option">use_lit_shell=&lt;bool&gt;</h3>
 <blockquote class="lit-option-desc">
 Enable or disable the use of LIT's internal shell in ShTests. If the enviroment
 variable <code>LIT_USE_INTERNAL_SHELL</code> is present then that is used as the
 default value. Otherwise the default value is <code>True</code> on Windows and
 <code>False</code> on every other platform.
 </blockquote>
 </p>

 <p>
 <h3 class="lit-option">no_default_flags=&lt;bool&gt;</h3>
 <blockquote class="lit-option-desc">
 <b>Default: </b><code>False</code></br>
 Disable all default compile and link flags from being added. When this option is
 used only flags specified using the <code>compile_flags</code> and
 <code>link_flags</code> will be used.
 </blockquote>
 </p>

 <p>
 <h3 class="lit-option">compile_flags="&lt;list-of-args&gt;"</h3>
 <blockquote class="lit-option-desc">
 Specify additional compile flags as a space delimited string.
 Note: This options should not be used to change the standard version used.
 </blockquote>
 </p>

 <p>
 <h3 class="lit-option">link_flags="&lt;list-of-args&gt;"</h3>
 <blockquote class="lit-option-desc">
 Specify additional link  flags as a space delimited string.
 </blockquote>
 </p>

 <p>
 <h3 class="lit-option">std=&lt;standard version&gt;</h3>
 <blockquote class="lit-option-desc">
 <b>Values: </b><code>c++98, c++03, c++11, c++14, c++1z</code></br>
 Change the standard version used when building the tests.
 </blockquote>
 </p>

 <p>
 <h3 class="lit-option">debug_level=&lt;level&gt;</h3>
 <blockquote class="lit-option-desc">
 <b>Values: </b><code>0, 1</code></br>
 Enable the use of debug mode. Level 0 enables assertions and level 1 enables
 assertions and debugging of iterator misuse.
 </blockquote>
 </p>

 <p>
 <h3 class="lit-option">use_sanitizer=&lt;sanitizer name&gt;</h3>
 <blockquote class="lit-option-desc">
 <b>Values: </b><code>Memory, MemoryWithOrigins, Address, Undefined</code></br>
 Run the tests using the given sanitizer. If <code>LLVM_USE_SANITIZER</code>
 was given when building libc++ then that sanitizer will be used by default.
 </blockquote>
 </p>

 <p>
 <h3 class="lit-option">color_diagnostics</h3>
 <blockquote class="lit-option-desc">
 Enable the use of colorized compile diagnostics. If the
 <code>color_diagnostics</code> option is specified or the enviroment variable
 <code>LIBCXX_COLOR_DIAGNOSTICS</code> is present then color diagnostics will be
 enabled.
 </blockquote>
 </p>

 </div>
 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
	"http://www.w3.org/TR/html4/strict.dtd">
	<!-- Material used from: HTML 4.01 specs: http://www.w3.org/TR/html401/ -->
	<html>
	<head>
	<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
	<title>Testing libc++ using LIT</title>
	<link type="text/css" rel="stylesheet" href="menu.css">
	<link type="text/css" rel="stylesheet" href="content.css">
	<style>
	.lit-option {
	padding-top: 0.5em;
	margin-bottom: 0.0em;
	font-size: medium;
	color: #2d58b7
	}
	.lit-option-desc {
	display: block;
	margin-top: 0em;
	margin-bottom: 0em;
	margin-left: 20px;
	margin-right: 20px;
	}
	</style>
	</head>

	<body>
	<div id="menu">
	<div>
	<a href="http://llvm.org/">LLVM Home</a>
	</div>

	<div class="submenu">
	<label>libc++ Info</label>
	<a href="/index.html">About</a>
	</div>

	<div class="submenu">
	<label>Quick Links</label>
	<a href="http://lists.llvm.org/mailman/listinfo/cfe-dev">cfe-dev</a>
	<a href="http://lists.llvm.org/mailman/listinfo/cfe-commits">cfe-commits</a>
	<a href="http://llvm.org/bugs/">Bug Reports</a>
	<a href="http://llvm.org/svn/llvm-project/libcxx/trunk/">Browse SVN</a>
	<a href="http://llvm.org/viewvc/llvm-project/libcxx/trunk/">Browse ViewVC</a>
	</div>
	</div>

	<div id="content">
	<!--*********************************************************************-->
	<h1>Testing libc++ using LIT</h1>
	<!--*********************************************************************-->
	<p>
	libc++ uses LIT to configure and run its tests. The primary way to run the
	libc++ tests is by using <code>make check-libcxx</code>. However since libc++
	can be used in any number of possible configurations it is important to
	customize the way LIT builds and runs the tests. This guide provides
	information on how to use LIT directly to test libc++.
	</p>
	<p>
	Documentation for LIT can be found
	<a href="http://llvm.org/docs/CommandGuide/lit.html">here</a>.
	</p>

	<!--*********************************************************************-->
	<h2>Getting Started</h2>
	<!--*********************************************************************-->
	<p>
	After building libc++ use the following commands before you start using LIT to
	test.
	</p>
	<ul>
	<li><code>alias lit='python path/to/llvm/utils/lit/lit.py'</code></li>
	<li><code>export LIBCXX_SITE_CONFIG=path/to/build-libcxx/test/lit.site.cfg</code></li>
	</ul>
	<p>
	You can now run the libc++ tests by running:
	</p>
	<ul>
	<li><code>cd path/to/libcxx</code></li>
	<li><code>lit -sv ./test</code></li>
	</ul>
	<p>
	To only run a subsection of the tests use:
	<ul>
	<li><code>lit -sv test/std/numerics # Run only the numeric tests</code></li>
	</ul>

	<!--*********************************************************************-->
	<h2>Customization Options</h2>
	<!--*********************************************************************-->
	<p>
	libc++'s testsuite provides multiple options to configure the way the tests
	are build and run. To use these options you pass them on the LIT command line
	as <code>--param NAME</code> or <code>--param NAME=VALUE</code>. Some options
	have default values specified during CMake's configuration. Passing the option
	on the command line will override the default.
	</p>


	<p>
	<h3 class="lit-option">libcxx_site_config=<path/to/lit.site.cfg></h3>
	<blockquote class="lit-option-desc">
	Specify the site configuration to use when running the tests. This option
	overrides the enviroment variable <code>LIBCXX_SITE_CONFIG</code>
	</blockquote>
	</p>

	<p>
	<h3 class="lit-option">libcxx_headers=<path/to/headers></h3>
	<blockquote class="lit-option-desc">
	Specify the libc++ headers that are tested. By default the headers in the source
	tree are used.
	</blockquote>
	</p>

	<p>
	<h3 class="lit-option">libcxx_library=<path/to/libc++.so></h3>
	<blockquote class="lit-option-desc">
	Specify the libc++ library that is tested. By default the library in the build
	directory is used. This option cannot be used when <code>use_system_lib</code>
	is provided.
	</blockquote>
	</p>

	<p>
	<h3 class="lit-option">use_system_lib=<bool></h3>
	<blockquote class="lit-option-desc">
	<b>Default: </b><code>False</code></br>
	Enable or disable testing against the installed version of libc++ library.
	Note: This does not use the installed headers.
	</blockquote>
	</p>

	<p>
	<h3 class="lit-option">use_lit_shell=<bool></h3>
	<blockquote class="lit-option-desc">
	Enable or disable the use of LIT's internal shell in ShTests. If the enviroment
	variable <code>LIT_USE_INTERNAL_SHELL</code> is present then that is used as the
	default value. Otherwise the default value is <code>True</code> on Windows and
	<code>False</code> on every other platform.
	</blockquote>
	</p>

	<p>
	<h3 class="lit-option">no_default_flags=<bool></h3>
	<blockquote class="lit-option-desc">
	<b>Default: </b><code>False</code></br>
	Disable all default compile and link flags from being added. When this option is
	used only flags specified using the <code>compile_flags</code> and
	<code>link_flags</code> will be used.
	</blockquote>
	</p>

	<p>
	<h3 class="lit-option">compile_flags="<list-of-args>"</h3>
	<blockquote class="lit-option-desc">
	Specify additional compile flags as a space delimited string.
	Note: This options should not be used to change the standard version used.
	</blockquote>
	</p>

	<p>
	<h3 class="lit-option">link_flags="<list-of-args>"</h3>
	<blockquote class="lit-option-desc">
	Specify additional link flags as a space delimited string.
	</blockquote>
	</p>

	<p>
	<h3 class="lit-option">std=<standard version></h3>
	<blockquote class="lit-option-desc">
	<b>Values: </b><code>c++98, c++03, c++11, c++14, c++1z</code></br>
	Change the standard version used when building the tests.
	</blockquote>
	</p>

	<p>
	<h3 class="lit-option">debug_level=<level></h3>
	<blockquote class="lit-option-desc">
	<b>Values: </b><code>0, 1</code></br>
	Enable the use of debug mode. Level 0 enables assertions and level 1 enables
	assertions and debugging of iterator misuse.
	</blockquote>
	</p>

	<p>
	<h3 class="lit-option">use_sanitizer=<sanitizer name></h3>
	<blockquote class="lit-option-desc">
	<b>Values: </b><code>Memory, MemoryWithOrigins, Address, Undefined</code></br>
	Run the tests using the given sanitizer. If <code>LLVM_USE_SANITIZER</code>
	was given when building libc++ then that sanitizer will be used by default.
	</blockquote>
	</p>

	<p>
	<h3 class="lit-option">color_diagnostics</h3>
	<blockquote class="lit-option-desc">
	Enable the use of colorized compile diagnostics. If the
	<code>color_diagnostics</code> option is specified or the enviroment variable
	<code>LIBCXX_COLOR_DIAGNOSTICS</code> is present then color diagnostics will be
	enabled.
	</blockquote>
	</p>

	</div>
	</body>
	</html>