update documentation
This commit is contained in:
deeaitch committed
1 parent
21d6f12163
commit
ef8e21db2e
20 files changed
+179
-58
No files matched your search
+114
-1
@@ -1139,9 +1139,122 @@ Configure the GCC coverage build in Qt Creator</h2>
|
||||
</div><!-- fragment --></li>
|
||||
<li>Run qmake and build the project. Both <code>dbc_tests</code> and <code>dbc_model_tests</code> must run to include coverage from the core and optional model adapter.</li>
|
||||
<li>In a terminal in the coverage build directory, compile the standalone test and run the LCOV/report commands above. Set <code>DBC_SOURCE_DIR</code> to the absolute repository path if using a new terminal. <code>make check</code> runs both QtTest executables; the standalone tree executable must be run separately.</li>
|
||||
<li>View <code>html/index.html</code> in a browser. This workflow produces HTML reports; it does not require a licensed coverage toolchain. </li>
|
||||
<li>View <code>html/index.html</code> in a browser. This workflow produces HTML reports; it does not require a licensed coverage toolchain.</li>
|
||||
</ol>
|
||||
<p></code></p>
|
||||
<p><code></code></p>
|
||||
<h2><a class="anchor" id="autotoc_md127"></a>
|
||||
Configure all build variants in Qt Creator</h2>
|
||||
<p><code></code></p>
|
||||
<p><code>The local <code>dbc.pro.user</code> stores machine-specific kit IDs and build/run settings. It is ignored by Git (<code>*.user</code>) and should not be committed or copied between machines. Recreate the configurations below through the UI when setting up a new checkout. The <code>Qt4ProjectManager</code> identifiers inside <code>.user</code> are historical Qt Creator setting names; the project still requires Qt 6.8.2.</code></p>
|
||||
<p><code>The local configuration set uses these independent build directories:</code></p>
|
||||
<p><code></p><table class="markdownTable">
|
||||
<tr class="markdownTableHead">
|
||||
<th class="markdownTableHeadNone">Configuration </th><th class="markdownTableHeadNone">Build directory example </th><th class="markdownTableHeadNone">Purpose </th></tr>
|
||||
<tr class="markdownTableRowOdd">
|
||||
<td class="markdownTableBodyNone">Debug </td><td class="markdownTableBodyNone"><code>/tmp/build/dbc/Desktop-Debug</code> </td><td class="markdownTableBodyNone">Core library and parser/decoder/coverage regression tests </td></tr>
|
||||
<tr class="markdownTableRowEven">
|
||||
<td class="markdownTableBodyNone">Release </td><td class="markdownTableBodyNone"><code>/tmp/build/dbc/Desktop-Release</code> </td><td class="markdownTableBodyNone">The same targets with release settings </td></tr>
|
||||
<tr class="markdownTableRowOdd">
|
||||
<td class="markdownTableBodyNone">Profile </td><td class="markdownTableBodyNone"><code>/tmp/build/dbc/Desktop-Profile</code> </td><td class="markdownTableBodyNone">Existing Qt Creator profiling configuration; not code coverage </td></tr>
|
||||
<tr class="markdownTableRowEven">
|
||||
<td class="markdownTableBodyNone">Debug Qt Models </td><td class="markdownTableBodyNone"><code>/tmp/build/dbc/Desktop-Debug-Qt-Models</code> </td><td class="markdownTableBodyNone">Debug targets plus optional adapter and model tests </td></tr>
|
||||
<tr class="markdownTableRowOdd">
|
||||
<td class="markdownTableBodyNone">Release Qt Models </td><td class="markdownTableBodyNone"><code>/tmp/build/dbc/Desktop-Release-Qt-Models</code> </td><td class="markdownTableBodyNone">Release targets plus optional adapter and model tests </td></tr>
|
||||
<tr class="markdownTableRowEven">
|
||||
<td class="markdownTableBodyNone">Debug Qt Models Strict </td><td class="markdownTableBodyNone"><code>/tmp/build/dbc/Desktop-Debug-Qt-Models-Strict</code> </td><td class="markdownTableBodyNone">Model build with <code>QT_FATAL_WARNINGS=1</code> for builds and runs </td></tr>
|
||||
<tr class="markdownTableRowOdd">
|
||||
<td class="markdownTableBodyNone">Coverage </td><td class="markdownTableBodyNone"><code>/tmp/build/dbc/Desktop-Coverage</code> </td><td class="markdownTableBodyNone">Instrumented core/model build, test execution, and LCOV HTML report </td></tr>
|
||||
<tr class="markdownTableRowEven">
|
||||
<td class="markdownTableBodyNone">Core Only </td><td class="markdownTableBodyNone"><code>/tmp/build/dbc/Desktop-Core-Only</code> </td><td class="markdownTableBodyNone">The Qt-free core static library </td></tr>
|
||||
<tr class="markdownTableRowOdd">
|
||||
<td class="markdownTableBodyNone">Tree Tests </td><td class="markdownTableBodyNone"><code>/tmp/build/dbc/Desktop-Tree-Tests</code> </td><td class="markdownTableBodyNone">Standalone C++17 tree test without Qt </td></tr>
|
||||
<tr class="markdownTableRowEven">
|
||||
<td class="markdownTableBodyNone">Demo </td><td class="markdownTableBodyNone"><code>/tmp/build/dbc/Desktop-Demo</code> </td><td class="markdownTableBodyNone">Core library and command-line demo </td></tr>
|
||||
</table>
|
||||
<p></code></p>
|
||||
<p><code>The temporary paths are examples; choose permanent build directories if desired. Do not share a build directory between these configurations.</code></p>
|
||||
<p><code>To add the ordinary qmake configurations:</code></p>
|
||||
<p><code></p><ol type="1">
|
||||
<li>Open <code>dbc.pro</code> with a GCC/Qt 6.8.2 kit.</li>
|
||||
<li>Go to <b>Projects > Build Settings</b>. Keep the existing Debug, Release, and Profile configurations. Remove or disable a Coco build step if one remains.</li>
|
||||
<li>Select Debug, press <b>Clone</b>, and name the clone <b>Debug Qt Models</b>. Set its build directory from the table and add <code>CONFIG+=dbc_qt</code> to the qmake step's <b>Additional arguments</b>.</li>
|
||||
<li>Clone Release as <b>Release Qt Models</b> with the same qmake argument and its own build directory.</li>
|
||||
<li>Clone Debug Qt Models as <b>Debug Qt Models Strict</b>. In <b>Build Environment</b>, add <code>QT_FATAL_WARNINGS=1</code>. Run configurations should use the build environment.</li>
|
||||
<li><p class="startli">Clone Debug Qt Models as <b>Coverage</b>. In qmake <b>Additional arguments</b>, use:</p>
|
||||
<div class="fragment"><div class="line">CONFIG+=dbc_qt CONFIG+=debug CONFIG-=release "QMAKE_CXXFLAGS+=--coverage -fprofile-abs-path" "QMAKE_LFLAGS+=--coverage"</div>
|
||||
</div><!-- fragment --></li>
|
||||
<li>For Coverage, select <b>Add Build Step > Custom Process Step</b> after qmake and Make, then set:</li>
|
||||
</ol>
|
||||
<p></code></p>
|
||||
<p><code></p><table class="markdownTable">
|
||||
<tr class="markdownTableHead">
|
||||
<th class="markdownTableHeadNone">Field </th><th class="markdownTableHeadNone">Value </th></tr>
|
||||
<tr class="markdownTableRowOdd">
|
||||
<td class="markdownTableBodyNone">Command </td><td class="markdownTableBodyNone"><code>/bin/sh</code> </td></tr>
|
||||
<tr class="markdownTableRowEven">
|
||||
<td class="markdownTableBodyNone">Arguments </td><td class="markdownTableBodyNone"><code>"%{sourceDir}/tests/coverage_report.sh" "%{sourceDir}" "%{buildDir}"</code> </td></tr>
|
||||
<tr class="markdownTableRowOdd">
|
||||
<td class="markdownTableBodyNone">Working directory </td><td class="markdownTableBodyNone"><code>%{buildDir}</code> </td></tr>
|
||||
</table>
|
||||
<p></code></p>
|
||||
<p><code> This script compiles the standalone tree test, resets counters, runs both QtTest executables and the tree test, and generates <code>%{buildDir}/html/index.html</code>. It stops if any test fails. Therefore building Coverage also executes tests. <code>lcov</code> and <code>genhtml</code> must be installed. Use this configuration with the GCC kit; <code>gcov</code> and the compiler used for the standalone test must match that kit.</p><ol type="1">
|
||||
<li>Run qmake and build each new configuration once. The default root builds expose <code>dbc_tests</code>; model configurations also expose <code>dbc_model_tests</code>.</li>
|
||||
</ol>
|
||||
<p></code></p>
|
||||
<p><code>Qt Creator expands <code>%{sourceDir}</code> and <code>%{buildDir}</code> in custom steps to the source and active build directories. Use the field's variable chooser if needed.</code></p>
|
||||
<p><code>For the three independent builds, clone Debug, assign the name and build directory from the table, and replace its qmake/Make build steps with the custom process steps below. These steps are local IDE settings and do not change <code>dbc.pro</code>. Give each step a descriptive name and retain the listed order.</code></p>
|
||||
<p><code>For <b>Core Only</b>:</code></p>
|
||||
<p><code></p><table class="markdownTable">
|
||||
<tr class="markdownTableHead">
|
||||
<th class="markdownTableHeadNone">Command </th><th class="markdownTableHeadNone">Arguments </th><th class="markdownTableHeadNone">Working directory </th></tr>
|
||||
<tr class="markdownTableRowOdd">
|
||||
<td class="markdownTableBodyNone"><code>/usr/bin/mkdir</code> </td><td class="markdownTableBodyNone"><code>-p "%{buildDir}"</code> </td><td class="markdownTableBodyNone"><code>%{sourceDir}</code> </td></tr>
|
||||
<tr class="markdownTableRowEven">
|
||||
<td class="markdownTableBodyNone"><code>/usr/bin/qmake6</code> </td><td class="markdownTableBodyNone"><code>"%{sourceDir}/core/core.pro" CONFIG+=debug CONFIG-=release</code> </td><td class="markdownTableBodyNone"><code>%{buildDir}</code> </td></tr>
|
||||
<tr class="markdownTableRowOdd">
|
||||
<td class="markdownTableBodyNone"><code>/usr/bin/make</code> </td><td class="markdownTableBodyNone"><code>-j4</code> </td><td class="markdownTableBodyNone"><code>%{buildDir}</code> </td></tr>
|
||||
</table>
|
||||
<p></code></p>
|
||||
<p><code>Keep a clean step with <code>make clean</code> in <code>%{buildDir}</code>. Core Only creates a static library, so there is no executable to run.</code></p>
|
||||
<p><code>For <b>Tree Tests</b>:</code></p>
|
||||
<p><code></p><ol type="1">
|
||||
<li>Add a custom step with command <code>/usr/bin/mkdir</code>, arguments <code>-p "%{buildDir}"</code>, and working directory <code>%{sourceDir}</code>.</li>
|
||||
<li><p class="startli">Add a custom step with command <code>/usr/bin/c++</code>, working directory <code>%{buildDir}</code>, and these arguments:</p>
|
||||
<div class="fragment"><div class="line">-std=c++17 -O0 -g -I"%{sourceDir}/core" "%{sourceDir}/tests/tree_node_test.cpp" "%{sourceDir}/core/tree_node.cpp" "%{sourceDir}/core/dbc_tree_builder.cpp" -o "%{buildDir}/tree_node_tests"</div>
|
||||
</div><!-- fragment --></li>
|
||||
<li>Remove the default Make clean step: this direct compiler build creates no Makefile. Run the resulting executable as described below.</li>
|
||||
</ol>
|
||||
<p></code></p>
|
||||
<p><code>For <b>Demo</b>:</code></p>
|
||||
<p><code></p><table class="markdownTable">
|
||||
<tr class="markdownTableHead">
|
||||
<th class="markdownTableHeadNone">Command </th><th class="markdownTableHeadNone">Arguments </th><th class="markdownTableHeadNone">Working directory </th></tr>
|
||||
<tr class="markdownTableRowOdd">
|
||||
<td class="markdownTableBodyNone"><code>/usr/bin/mkdir</code> </td><td class="markdownTableBodyNone"><code>-p "%{buildDir}/core" "%{buildDir}/examples"</code> </td><td class="markdownTableBodyNone"><code>%{sourceDir}</code> </td></tr>
|
||||
<tr class="markdownTableRowEven">
|
||||
<td class="markdownTableBodyNone"><code>/usr/bin/qmake6</code> </td><td class="markdownTableBodyNone"><code>"%{sourceDir}/core/core.pro" CONFIG+=debug CONFIG-=release</code> </td><td class="markdownTableBodyNone"><code>%{buildDir}/core</code> </td></tr>
|
||||
<tr class="markdownTableRowOdd">
|
||||
<td class="markdownTableBodyNone"><code>/usr/bin/make</code> </td><td class="markdownTableBodyNone"><code>-j4</code> </td><td class="markdownTableBodyNone"><code>%{buildDir}/core</code> </td></tr>
|
||||
<tr class="markdownTableRowEven">
|
||||
<td class="markdownTableBodyNone"><code>/usr/bin/qmake6</code> </td><td class="markdownTableBodyNone"><code>"%{sourceDir}/examples/demo.pro" "DBC_CORE_BUILD_DIR=%{buildDir}/core" CONFIG+=debug CONFIG-=release</code> </td><td class="markdownTableBodyNone"><code>%{buildDir}/examples</code> </td></tr>
|
||||
<tr class="markdownTableRowOdd">
|
||||
<td class="markdownTableBodyNone"><code>/usr/bin/make</code> </td><td class="markdownTableBodyNone"><code>-j4</code> </td><td class="markdownTableBodyNone"><code>%{buildDir}/examples</code> </td></tr>
|
||||
</table>
|
||||
<p></code></p>
|
||||
<p><code>Replace the default clean step with two custom steps: <code>/usr/bin/make</code> with arguments <code>clean</code>, first in <code>%{buildDir}/examples</code>, then in <code>%{buildDir}/core</code>.</code></p>
|
||||
<p><code>To configure execution and switch variants:</code></p>
|
||||
<p><code></p><ol type="1">
|
||||
<li>Go to <b>Projects > Run Settings</b> and select the appropriate qmake target: <code>dbc_tests</code> for ordinary builds or <code>dbc_model_tests</code> for model builds.</li>
|
||||
<li>To run all QtTest suites together, add a <b>Custom Executable</b> named <b>All QtTest suites</b>, with executable <code>/usr/bin/make</code>, arguments <code>check</code>, and working directory <code>%{buildDir}</code>. Use it with an ordinary or model qmake configuration. Coverage already runs every test in its final build step.</li>
|
||||
<li>For Tree Tests, add a <b>Custom Executable</b> named <b>Standalone tree test</b>, executable <code>%{buildDir}/tree_node_tests</code>, working directory <code>%{buildDir}</code>, and no arguments.</li>
|
||||
<li>For Demo, add a <b>Custom Executable</b> named <b>Demo</b>, executable <code>%{buildDir}/examples/dbc_demo</code>, working directory <code>%{buildDir}/examples</code>. Set <b>Command line arguments</b> to the quoted absolute path of your DBC file.</li>
|
||||
<li>For Coverage on Linux, optionally add a <b>Custom Executable</b> named <b>Coverage HTML report</b>, executable <code>/usr/bin/xdg-open</code>, arguments <code>"%{buildDir}/html/index.html"</code>, working directory <code>%{buildDir}</code>. Running it opens the generated report in the default browser.</li>
|
||||
<li>Use the kit/build/run selector above the Run button to choose the build configuration and its corresponding executable. Build with <b>Ctrl+B</b>, then run with <b>Ctrl+R</b>. The Build Settings configuration list can also switch the active build.</li>
|
||||
<li>If <code>.user</code> was edited externally, close and reopen the project so Qt Creator reads the new settings. Do not edit it while the project is open, because Qt Creator can overwrite external changes when saving its session.</li>
|
||||
</ol>
|
||||
<p></code></p>
|
||||
<p><code>See Qt Creator's <a href="https://doc.qt.io/qtcreator/creator-build-settings.html">build configuration guide</a> and <a href="https://doc.qt.io/qtcreator/creator-run-settings.html">run configuration guide</a>. </code></p>
|
||||
</div></div><!-- contents -->
|
||||
</div><!-- PageDoc -->
|
||||
</div><!-- doc-content -->
|
||||
|
||||
Reference in new issue
Block a user