-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
266 lines (264 loc) · 18.2 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.15"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Embedded Artistry Framework: Embedded Artistry's Embedded Virtual Machine</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">Embedded Artistry Framework
</div>
<div id="projectbrief">Embedded Systems C++ Framework</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.15 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="PageDoc"><div class="header">
<div class="headertitle">
<div class="title">Embedded Artistry's Embedded Virtual Machine </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p><b>Table of Contents</b></p>
<ol type="1">
<li><a href="#about-the-embedded-virtual-machine">About the Embedded Virtual Machine</a></li>
<li><a href="#documentation-overview">Documentation Overview</a></li>
<li><a href="#getting-started">Getting Started</a><ol type="a">
<li><a href="#dependencies">Dependencies</a><ol type="i">
<li><a href="#git-lfs">git-lfs</a></li>
<li><a href="#meson">meson</a></li>
<li><a href="#adr-tools">adr-tools</a></li>
</ol>
</li>
<li><a href="#getting-the-source">Getting the Source</a></li>
<li><a href="#building-the-framework">Building the Framework</a><ol type="i">
<li><a href="#listing-targets">Listing Targets</a></li>
<li><a href="#cross-compilation">Cross-compilation</a></li>
<li><a href="#debug-vs-release">Debug vs Release</a></li>
</ol>
</li>
<li><a href="#building-documentation">Building Documentation</a></li>
<li><a href="#running-tests">Running Tests</a></li>
<li><a href="#running-static-analysis">Running Static Analysis</a></li>
<li><a href="#running-demo-applications">Running Demo Applications</a></li>
<li><a href="#buildling-your-own-framework-program">Building Your Own Framework Program</a></li>
</ol>
</li>
<li><a href="#build-configuration-options">Build Configuration Options</a></li>
<li><a href="#formatting">Formatting</a></li>
<li><a href="#release-process">Release Process</a></li>
</ol>
<ol type="1">
<li><a href="#need-help">Need Help?</a></li>
<li><a href="#authors">Authors</a></li>
<li><a href="#license">License</a></li>
<li><a href="#acknowledgments">Acknowledgments</a></li>
</ol>
<h2>About the Embedded Virtual Machine</h2>
<h2>Documentation Overview</h2>
<ul>
<li>The Glossary contains definitions for concepts used in the documentation and code</li>
<li>The <a href="docs/software_inventory.xlsx">Software Inventory</a> contains a list of all open source projects included in this framework, with version numbers and licensing information</li>
<li>The <a href="docs/development">Development/</a> folder contains guidelines for developers who are building framework components:<ul>
<li>Developer Guide contains guidelines for developers working on the project</li>
<li>C++ Guidelines contains guidelines for the C++ code used in the framework</li>
<li>Documentation Guidelines clarify documentation practices for framework modules</li>
<li>Error Model describes the framework's approach to error handling</li>
<li><a href="docs/development/namespaces.xlsx">Namespaces.xlsx</a> contains a list of namespaces defined by the framework</li>
<li>Refactoring provides guidelines for cleaning up existing code</li>
<li>The <a href="docs/development/patterns">Patterns/</a> directory contains notes about patterns used throughout the framework</li>
<li>The <a href="docs/development/references">References/</a> directory contains useful references for developers</li>
</ul>
</li>
</ul>
<h2>Getting Started</h2>
<ol type="1">
<li><a href="#dependencies">Dependencies</a><ol type="a">
<li><a href="#git-lfs">git-lfs</a></li>
<li><a href="#meson">meson</a></li>
</ol>
</li>
<li><a href="#building-the-framework">Building the Framework</a></li>
<li><a href="#building-documentation">Building Documentation</a></li>
</ol>
<ol type="1">
<li><a href="#running-tests">Running Tests</a></li>
<li><a href="#running-demo-applications">Running Demo Applications</a></li>
<li><a href="#buildling-your-own-framework-program">Building Your Own Framework Program</a></li>
</ol>
<h3>Dependencies</h3>
<p>The primary requirements for building the framework are:</p>
<ul>
<li><a href="#meson">meson</a> (build system)</li>
<li>A C++17-capable compiler for the host machine (simulator applications and tests)</li>
<li>A C++17-capable compiler for the target machine</li>
</ul>
<p>For access to the full framework documentation, you will need <a href="#git-lfs"><code>git-lfs</code></a>.</p>
<p>A variety of support tools are used by the framework for testing and static analysis:</p>
<ul>
<li>lizard (ccc)</li>
<li>brew install gcovr (code coverage)</li>
<li>unittest-cpp (to run ETL unit tests)</li>
<li>cmocka (to run libmemory and libc unit tests)</li>
</ul>
<p>To develop for the framework, you will need:</p>
<ul>
<li><a href="#adr-tools">adr-tools</a></li>
<li><a href="#pottery">pottery</a></li>
</ul>
<h4>git-lfs</h4>
<p>This repository requires git-lfs. If you do not have this installed, please visit <a href="https://git-lfs.github.com">the git-lfs web page</a>.</p>
<p>If you cloned this repository before installing git-lfs, please run <code>git lfs pull</code>. Otherwise clone will automatically perform a <code>git lfs pull</code>.</p>
<h4>meson</h4>
<p>This repository builds with <a href="https://mesonbuild.com">meson</a>, which requires Python 3 and Ninja.</p>
<p>To install on Linux:</p>
<div class="fragment"><div class="line">sudo apt-get install python3 python3-pip ninja-build</div></div><!-- fragment --><p>To install on OS X:</p>
<div class="fragment"><div class="line">brew install python3 ninja</div></div><!-- fragment --><p>Meson can be installed through <code>pip3</code>:</p>
<div class="fragment"><div class="line">pip3 install meson</div></div><!-- fragment --><p>If you want to install Meson globally on Linux, use:</p>
<div class="fragment"><div class="line">sudo -H pip3 install meson</div></div><!-- fragment --><h4>adr-tools</h4>
<p>This repository uses <a href="https://embeddedartistry.com/blog/2018/4/5/documenting-architectural-decisions-within-our-repositories">Architecture Decision Records</a>. Please install <a href="https://github.com/npryce/adr-tools"><code>adr-tools</code></a> to contribute to architecture decisions.</p>
<p>If you are using OSX, you can install <code>adr-tools</code> through Homebrew:</p>
<div class="fragment"><div class="line">brew install adr-tools</div></div><!-- fragment --><p>If you are using Windows or Linux, please install <code>adr-tools</code> via <a href="https://github.com/npryce/adr-tools">GitHub</a>.</p>
<h4>pottery</h4>
<p>TBD</p>
<h4>Supporting Tools</h4>
<ul>
<li>lizard (ccc)</li>
<li>brew install gcovr (code coverage)</li>
<li>clang-format</li>
<li><a href="https://cmocka.org">cmocka</a> (for some framework tests)</li>
<li>vale</li>
<li>Doxygen</li>
<li>cppcheck</li>
<li>clang-analyze</li>
</ul>
<h3>Getting the Source</h3>
<p>This project uses <code>git-lfs</code>, so please install it before cloning. If you cloned prior to installing <code>git-lfs</code>, simply run <code>git lfs pull</code> after installation.</p>
<p>This project is [hosted on GitHub][8]. You can clone the project directly using this command:</p>
<div class="fragment"><div class="line">git clone --recursive [email protected]:embeddedartistry/libc.git</div></div><!-- fragment --><h3>Building the Framework</h3>
<p>To build all framework components, you can run <code>make</code> at the project root. All build output will be placed in the <code>buildresults</code> folder by default.</p>
<p>You can specify another build output folder for use with <code>meson</code>. You can invoke the build using:</p>
<div class="fragment"><div class="line">$ meson your-buildresult-folder [options]</div><div class="line">$ meson arm_build --buildtype release --cross-file build/cross/gcc/arm/gcc_arm_cortex-m4.txt</div></div><!-- fragment --><p>Depending on the target architecture and its supported functionality, some items may need to be disabled. For example, this command disables threading and <code>std::chrono</code>:</p>
<div class="fragment"><div class="line">meson buildresults --cross-file build/cross/gcc/arm/gcc_arm_cortex-m4.txt -Dlibcxx-enable-chrono=false -Denable-threading=false</div></div><!-- fragment --><p>You can enable threading support with an RTOS and the C++ standard library using the <code>libcxx-thread-library</code> and <code>os-header-path</code> options. <code>os-header-path</code> is specified relative to the <code>libcpp</code> directory.</p>
<div class="fragment"><div class="line">meson buildresults --cross-file build/cross/gcc/arm/gcc_arm_cortex-m4.txt -Dlibcxx-thread-library=threadx -Duse-ea-libc=true -Dos-header-path=../../os/threadx/include</div></div><!-- fragment --><p>Once the directory has been created by <code>meson</code>, you can build all targets with <code>make</code>:</p>
<div class="fragment"><div class="line">$ make</div></div><!-- fragment --><p>Individual targets can be built within the <code>buildresults</code> folder:</p>
<div class="fragment"><div class="line">06:36:30 libcpp$ cd buildresults/</div><div class="line">06:37:18 buildresults$ ninja libc++.a</div><div class="line">[5/5] Generating install-cpp-headers with a custom command.</div></div><!-- fragment --><h4>Listing Targets</h4>
<h4>Cross-Compilation</h4>
<p>Example cross-compilation:</p>
<div class="fragment"><div class="line">meson buildresults --cross-file build/cross/gcc/arm/gcc_arm_cortex-m4.txt</div></div><!-- fragment --><h4>Debug vs Release</h4>
<p>By default, the project is configured to generate release builds. This means that debug symbols are not provided. The default optimization level for the framework is <code>-O2</code>.</p>
<p>To build a debug variant, you will need to manually configure the meson project and use the <code>--debug</code> option. You may also optionally set the <code>--optimization</code> option to <code>g</code> for an optimized debug build.</p>
<div class="fragment"><div class="line">meson buildresults --debug --optimization g</div></div><!-- fragment --><h3>Building Documentation</h3>
<p>To generate the Doxygen documentation, run <code>make docs</code> at the project root. Documentation will be placed into <code>buildresults/documentation/html</code>. You can open <code>index.html</code> to access the document root.</p>
<h3>Running Tests</h3>
<p>The framework uses Catch for unit testing. Some dependencies use CMocka. If CMocka is not installed on your system, the tests will not be built or run.</p>
<p>To run the framework tests and print the results to console:</p>
<div class="fragment"><div class="line">$ make test-framework</div></div><!-- fragment --><p>To run all the framework unit tests:</p>
<div class="fragment"><div class="line">$ make test</div><div class="line">1/4 libmemory / libmemory_freelist_tests OK 0.02 s</div><div class="line">2/4 libc / printf_tests OK 0.02 s</div><div class="line">3/4 libc / libc_tests OK 0.07 s</div><div class="line">4/4 Framework / framework_tests OK 0.17 s</div><div class="line"></div><div class="line">OK: 4</div><div class="line">FAIL: 0</div><div class="line">SKIP: 0</div><div class="line">TIMEOUT: 0</div></div><!-- fragment --><p>Test results for the framework will be output into <code>buildresults/framework_tests.xml</code>. Module test results will be found in <code>buildresults/test</code>.</p>
<h3>Running Static Analysis</h3>
<p>TBD</p>
<h3>Running Demo Applications</h3>
<p>TBD</p>
<h3>Building Your Own Framework Program</h3>
<p>TBD</p>
<h2>Build Configuration Options</h2>
<p>Our meson build can be configured in a variety of the ways through.</p>
<h3>Debug</h3>
<p>By default, the framework is built in release mode. To enable a debug build, you must supply the meson configuration option <code>--debug</code>.</p>
<div class="fragment"><div class="line">meson buildresults --debug --optimization g</div></div><!-- fragment --><h3>Optimization</h3>
<p>The optimization level for the framework defaults to <code>-O2</code>.</p>
<p>To modify the optimization level, you must supply the meson configuration option <code>--optimization</code>.</p>
<div class="fragment"><div class="line">meson buildresults --debug --optimization g</div><div class="line">meson buildresults --debug --optimization 1</div></div><!-- fragment --><h3>Vendor SDK Path</h3>
<p>Your project may need a vendor SDK, especially for migratory purposes. You can use the <code>vendor-sdk-path</code> option to provide a path to this SDK:</p>
<div class="fragment"><div class="line">option('vendor-sdk-path', type: 'string', value: '')</div></div><!-- fragment --><p>The vendor SDK path is relative to where the binaries are declared, or where the path is first used. This is not relative to the top level of the framework. This can be confusing.</p>
<p>So if you are at:</p>
<div class="fragment"><div class="line">~/src/ea/embedded-framework</div></div><!-- fragment --><p>And the SDK is at: </p><div class="fragment"><div class="line">~/Downloads/nRF5_SDK_15.3.0_59ac345</div></div><!-- fragment --><p>And the binary build folder where you use the SDK is at:</p>
<div class="fragment"><div class="line">embedded-framework/src/applications/nrf52</div></div><!-- fragment --><p>Then you need to use this path:</p>
<div class="fragment"><div class="line">../../../../../../Downloads/nRF5_SDK_15.3.0_59ac345</div></div><!-- fragment --><p>Here's an example invocation using the NRF52 SDK:</p>
<div class="fragment"><div class="line">meson buildresults --cross-file=build/cross/gcc/arm/nrf52840.txt -Dvendor-sdk-path=../../../../../../Downloads/nRF5_SDK_15.3.0_59ac345</div></div><!-- fragment --><h2>Formatting</h2>
<p>This repository enforces formatting using <a href="https://clang.llvm.org/docs/ClangFormat.html"><code>clang-format</code></a>.</p>
<p>You can auto-format your code to match the style guidelines by issuing the following command:</p>
<div class="fragment"><div class="line">make format</div></div><!-- fragment --><p>Formatting is enforced by the Jenkins build server which runs continuous integration for this project. Your pull request will not be accepted if the formatting check fails.</p>
<h2>Release Process</h2>
<h2>Need Help?</h2>
<p>If you need further assistance or have any questions, please <a href="https://github.com/embeddedartistry/embedded-framework/issues/new">file a GitHub Issue</a> or send us an email using the <a href="http://embeddedartistry.com/contact">Embedded Artistry Contact Form</a>.</p>
<p>You can also <a href="https://twitter.com/mbeddedartistry/">reach out on Twitter: mbeddedartistry</a>.</p>
<h2>Authors</h2>
<ul>
<li><b><a href="https://github.com/phillipjohnston">Phillip Johnston</a></b> - original framework author - <a href="https://github.com/embeddedartistry">Embedded Artistry</a></li>
</ul>
<h2>License</h2>
<p>The framework is Copyright © 2018 Embedded Artistry LLC.</p>
<p>TBD</p>
<p>A full list of open source modules and their licenses can be found in the <a href="docs/development/software_inventory.xlsx">Software Inventory</a>.</p>
<h2>Acknowledgments</h2>
<p>I would like to thank the following individuals for their direct contributions to this project:</p>
<ul>
<li>Rozi Harris, who has tirelessly listened to ideas, reviewed the framework architecture, and edited documentation</li>
</ul>
<p>I would like to thank the following individuals for their inspiration on this project:</p>
<ul>
<li>Ruth Malan, who inspired the architecture documentation and process</li>
<li>James Grenning, who taught me the value of Test-Driven Development (TDD)</li>
<li>Jerry Fitzpatrick, who inspired many of the guidelines and practices that were used to build this framework</li>
</ul>
<p>I would like to thank the following individuals for the open source libraries that have been incorporated into this framework:</p>
<ul>
<li>John Wellbelove for the <a href="http://etlcppc.com">Embedded Template Library</a></li>
<li>Jonathan Müller for <a href="https://github.com/foonathan/type_safe">type_safe</a> and <a href="https://github.com/foonathan/debug_assert">debug_assert</a> </li>
</ul>
</div></div><!-- PageDoc -->
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.15
</small></address>
</body>
</html>