1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 2 "http://www.w3.org/TR/html4/strict.dtd"> 3 <!-- Material used from: HTML 4.01 specs: http://www.w3.org/TR/html401/ --> 4 <html> 5 <head> 6 <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 7 <title>Testing libc++ using LIT</title> 8 <link type="text/css" rel="stylesheet" href="menu.css"> 9 <link type="text/css" rel="stylesheet" href="content.css"> 10 <style> 11 .lit-option { 12 padding-top: 0.5em; 13 margin-bottom: 0.0em; 14 font-size: medium; 15 color: #2d58b7 16 } 17 .lit-option-desc { 18 display: block; 19 margin-top: 0em; 20 margin-bottom: 0em; 21 margin-left: 20px; 22 margin-right: 20px; 23 } 24 </style> 25 </head> 26 27 <body> 28 <div id="menu"> 29 <div> 30 <a href="http://llvm.org/">LLVM Home</a> 31 </div> 32 33 <div class="submenu"> 34 <label>libc++ Info</label> 35 <a href="/index.html">About</a> 36 </div> 37 38 <div class="submenu"> 39 <label>Quick Links</label> 40 <a href="http://lists.llvm.org/mailman/listinfo/cfe-dev">cfe-dev</a> 41 <a href="http://lists.llvm.org/mailman/listinfo/cfe-commits">cfe-commits</a> 42 <a href="http://llvm.org/bugs/">Bug Reports</a> 43 <a href="http://llvm.org/svn/llvm-project/libcxx/trunk/">Browse SVN</a> 44 <a href="http://llvm.org/viewvc/llvm-project/libcxx/trunk/">Browse ViewVC</a> 45 </div> 46 </div> 47 48 <div id="content"> 49 <!--*********************************************************************--> 50 <h1>Testing libc++ using LIT</h1> 51 <!--*********************************************************************--> 52 <p> 53 libc++ uses LIT to configure and run its tests. The primary way to run the 54 libc++ tests is by using <code>make check-libcxx</code>. However since libc++ 55 can be used in any number of possible configurations it is important to 56 customize the way LIT builds and runs the tests. This guide provides 57 information on how to use LIT directly to test libc++. 58 </p> 59 <p> 60 Documentation for LIT can be found 61 <a href="http://llvm.org/docs/CommandGuide/lit.html">here</a>. 62 </p> 63 64 <!--*********************************************************************--> 65 <h2>Getting Started</h2> 66 <!--*********************************************************************--> 67 <p> 68 After building libc++ use the following commands before you start using LIT to 69 test. 70 </p> 71 <ul> 72 <li><code>alias lit='python path/to/llvm/utils/lit/lit.py'</code></li> 73 <li><code>export LIBCXX_SITE_CONFIG=path/to/build-libcxx/test/lit.site.cfg</code></li> 74 </ul> 75 <p> 76 You can now run the libc++ tests by running: 77 </p> 78 <ul> 79 <li><code>cd path/to/libcxx</code></li> 80 <li><code>lit -sv ./test</code></li> 81 </ul> 82 <p> 83 To only run a subsection of the tests use: 84 <ul> 85 <li><code>lit -sv test/std/numerics # Run only the numeric tests</code></li> 86 </ul> 87 88 <!--*********************************************************************--> 89 <h2>Customization Options</h2> 90 <!--*********************************************************************--> 91 <p> 92 libc++'s testsuite provides multiple options to configure the way the tests 93 are build and run. To use these options you pass them on the LIT command line 94 as <code>--param NAME</code> or <code>--param NAME=VALUE</code>. Some options 95 have default values specified during CMake's configuration. Passing the option 96 on the command line will override the default. 97 </p> 98 99 100 <p> 101 <h3 class="lit-option">libcxx_site_config=<path/to/lit.site.cfg></h3> 102 <blockquote class="lit-option-desc"> 103 Specify the site configuration to use when running the tests. This option 104 overrides the enviroment variable <code>LIBCXX_SITE_CONFIG</code> 105 </blockquote> 106 </p> 107 108 <p> 109 <h3 class="lit-option">libcxx_headers=<path/to/headers></h3> 110 <blockquote class="lit-option-desc"> 111 Specify the libc++ headers that are tested. By default the headers in the source 112 tree are used. 113 </blockquote> 114 </p> 115 116 <p> 117 <h3 class="lit-option">libcxx_library=<path/to/libc++.so></h3> 118 <blockquote class="lit-option-desc"> 119 Specify the libc++ library that is tested. By default the library in the build 120 directory is used. This option cannot be used when <code>use_system_lib</code> 121 is provided. 122 </blockquote> 123 </p> 124 125 <p> 126 <h3 class="lit-option">use_system_lib=<bool></h3> 127 <blockquote class="lit-option-desc"> 128 <b>Default: </b><code>False</code></br> 129 Enable or disable testing against the installed version of libc++ library. 130 Note: This does not use the installed headers. 131 </blockquote> 132 </p> 133 134 <p> 135 <h3 class="lit-option">use_lit_shell=<bool></h3> 136 <blockquote class="lit-option-desc"> 137 Enable or disable the use of LIT's internal shell in ShTests. If the enviroment 138 variable <code>LIT_USE_INTERNAL_SHELL</code> is present then that is used as the 139 default value. Otherwise the default value is <code>True</code> on Windows and 140 <code>False</code> on every other platform. 141 </blockquote> 142 </p> 143 144 <p> 145 <h3 class="lit-option">no_default_flags=<bool></h3> 146 <blockquote class="lit-option-desc"> 147 <b>Default: </b><code>False</code></br> 148 Disable all default compile and link flags from being added. When this option is 149 used only flags specified using the <code>compile_flags</code> and 150 <code>link_flags</code> will be used. 151 </blockquote> 152 </p> 153 154 <p> 155 <h3 class="lit-option">compile_flags="<list-of-args>"</h3> 156 <blockquote class="lit-option-desc"> 157 Specify additional compile flags as a space delimited string. 158 Note: This options should not be used to change the standard version used. 159 </blockquote> 160 </p> 161 162 <p> 163 <h3 class="lit-option">link_flags="<list-of-args>"</h3> 164 <blockquote class="lit-option-desc"> 165 Specify additional link flags as a space delimited string. 166 </blockquote> 167 </p> 168 169 <p> 170 <h3 class="lit-option">std=<standard version></h3> 171 <blockquote class="lit-option-desc"> 172 <b>Values: </b><code>c++98, c++03, c++11, c++14, c++1z</code></br> 173 Change the standard version used when building the tests. 174 </blockquote> 175 </p> 176 177 <p> 178 <h3 class="lit-option">debug_level=<level></h3> 179 <blockquote class="lit-option-desc"> 180 <b>Values: </b><code>0, 1</code></br> 181 Enable the use of debug mode. Level 0 enables assertions and level 1 enables 182 assertions and debugging of iterator misuse. 183 </blockquote> 184 </p> 185 186 <p> 187 <h3 class="lit-option">use_sanitizer=<sanitizer name></h3> 188 <blockquote class="lit-option-desc"> 189 <b>Values: </b><code>Memory, MemoryWithOrigins, Address, Undefined</code></br> 190 Run the tests using the given sanitizer. If <code>LLVM_USE_SANITIZER</code> 191 was given when building libc++ then that sanitizer will be used by default. 192 </blockquote> 193 </p> 194 195 <p> 196 <h3 class="lit-option">color_diagnostics</h3> 197 <blockquote class="lit-option-desc"> 198 Enable the use of colorized compile diagnostics. If the 199 <code>color_diagnostics</code> option is specified or the enviroment variable 200 <code>LIBCXX_COLOR_DIAGNOSTICS</code> is present then color diagnostics will be 201 enabled. 202 </blockquote> 203 </p> 204 205 </div> 206 </body> 207 </html> 208
