blob: fbca6fe00ce212fab27854bed3961b5ffcda634e [file] [log] [blame]
<!--
Documentation/_templates/layout.html
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership. The
ASF licenses this file to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance with the
License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
-->
<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Quickstart &mdash; NuttX latest documentation</title>
<link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../_static/sphinx_tabs/semantic-ui-2.4.1/segment.min.css" type="text/css" />
<link rel="stylesheet" href="../_static/sphinx_tabs/semantic-ui-2.4.1/menu.min.css" type="text/css" />
<link rel="stylesheet" href="../_static/sphinx_tabs/semantic-ui-2.4.1/tab.min.css" type="text/css" />
<link rel="stylesheet" href="../_static/sphinx_tabs/tabs.css" type="text/css" />
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<!--[if lt IE 9]>
<script src="../_static/js/html5shiv.min.js"></script>
<![endif]-->
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script src="../_static/sphinx_tabs/semantic-ui-2.4.1/tab.min.js"></script>
<script src="../_static/sphinx_tabs/tabs.js"></script>
<script type="text/javascript" src="../_static/js/theme.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Installing" href="install.html" />
<link rel="prev" title="Getting Started" href="index.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../index.html" class="icon icon-home"> NuttX
<img src="../_static/NuttX.png" class="logo" alt="Logo"/>
</a>
<!-- this version selector is quite ugly, should be probably replaced by something
more modern -->
<div class="version-selector">
<select>
<option value="latest" selected="selected">latest</option>
</select>
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<p class="caption"><span class="caption-text">Table of Contents</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../index.html">Home</a></li>
<li class="toctree-l1"><a class="reference internal" href="../introduction/index.html">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="../introduction/inviolables.html">The Inviolable Principles of NuttX</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Getting Started</a><ul class="current">
<li class="toctree-l2 current"><a class="current reference internal" href="#">Quickstart</a></li>
<li class="toctree-l2"><a class="reference internal" href="install.html">Installing</a></li>
<li class="toctree-l2"><a class="reference internal" href="compiling.html">Compiling</a></li>
<li class="toctree-l2"><a class="reference internal" href="running.html">Running</a></li>
<li class="toctree-l2"><a class="reference internal" href="configuring.html">Configuring</a></li>
<li class="toctree-l2"><a class="reference internal" href="debugging.html">Debugging</a></li>
<li class="toctree-l2"><a class="reference internal" href="organization.html">Directory Structure</a></li>
<li class="toctree-l2"><a class="reference internal" href="build_and_make.html">Build and Make Details</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../components/index.html">OS Components</a></li>
<li class="toctree-l1"><a class="reference internal" href="../applications/index.html">Applications</a></li>
<li class="toctree-l1"><a class="reference internal" href="../boards/index.html">Supported Boards</a></li>
<li class="toctree-l1"><a class="reference internal" href="../reference/index.html">API Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="../guides/index.html">Guides</a></li>
<li class="toctree-l1"><a class="reference internal" href="../releases/index.html">Releases</a></li>
<li class="toctree-l1"><a class="reference internal" href="../contributing/index.html">Contributing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">NuttX</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html" class="icon icon-home"></a> &raquo;</li>
<li><a href="index.html">Getting Started</a> &raquo;</li>
<li>Quickstart</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/quickstart/quickstart.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="quickstart">
<span id="id1"></span><h1>Quickstart<a class="headerlink" href="#quickstart" title="Permalink to this headline"></a></h1>
<p>Here’s the quick version of getting started with NuttX. This is a bare-bones outline for experienced developers– if it’s
going too quickly, dive into the following sections. This Quickstart guide assumes you’re on a Linux
computer, you’re using an ARM microcontroller on your embedded board, and you’re familiar with using the command line.</p>
<ol class="arabic">
<li><p>Install a Cross-Compiler Toolchain</p>
<p>With NuttX, you compile the operating system and your application on your desktop or laptop computer, then install the
binary file on your embedded computer. This guide assumes your computer is an
<a class="reference external" href="https://en.wikipedia.org/wiki/ARM_architecture">ARM</a> CPU. If it isn’t, you’ll need a different tool chain.</p>
<p>You can download a toolchain from
<a class="reference external" href="https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm">ARM Embedded GNU Toolchain</a>
for your embedded processor’s CPU. You can also use a toolchain shipped with your OS for the <cite>none-eabi</cite> target, such as <cite>gcc-arm-none-eabi</cite> in Linux.</p>
<p>In the following example, we download <code class="docutils literal notranslate"><span class="pre">gcc-arm-none-eabi</span></code> version 9.0 and unpack it into <code class="docutils literal notranslate"><span class="pre">/opt/gcc</span></code>:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> sudo mkdir /opt/gcc
<span class="gp">$</span> sudo chgrp -R users /opt/gcc
<span class="gp">$</span> <span class="nb">cd</span> /opt/gcc
<span class="gp">$</span> wget https://developer.arm.com/-/media/Files/downloads/gnu-rm/9-2019q4/gcc-arm-none-eabi-9-2019-q4-major-x86_64-linux.tar.bz2
<span class="gp">$</span> tar xf gcc-arm-none-eabi-9-2019-q4-major-x86_64-linux.tar.bz2
</pre></div>
</div>
<p>Then, add the toolchain <code class="docutils literal notranslate"><span class="pre">bin/</span></code> directory to your path:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> <span class="nb">echo</span> <span class="s2">&quot;export PATH=/opt/gcc/gcc-arm-none-eabi-9-2019-q4-major/bin:</span><span class="nv">$PATH</span><span class="s2">&quot;</span> &gt;&gt; ~/.bashrc
</pre></div>
</div>
<p>If you are using any other shell, the procedure is similar by editing the corresponding rc file.</p>
</li>
<li><p>Download Apache NuttX</p>
<p>The next step is to download NuttX main repository along the application repository. The latter is technically optional in a very minimal configurations but should be included in normal configuration since it includes the NuttX shell.</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> mkdir nuttx
<span class="gp">$</span> <span class="nb">cd</span> nuttx
<span class="gp">$</span> git clone https://github.com/apache/incubator-nuttx.git nuttx
<span class="gp">$</span> git clone https://github.com/apache/incubator-nuttx-apps apps
<span class="gp">$</span> git clone https://bitbucket.org/nuttx/tools.git tools
</pre></div>
</div>
</li>
<li><p>Install the <code class="docutils literal notranslate"><span class="pre">kconfig-frontends</span></code> package</p>
<p>NuttX is configured using <code class="docutils literal notranslate"><span class="pre">kconfig</span></code> system via an interactive menu system (<code class="docutils literal notranslate"><span class="pre">menuconfig</span></code>). It also includes the <code class="docutils literal notranslate"><span class="pre">kconfig-tweak</span></code> utility that can be used to quickly change debug settings without going into the menu system.</p>
<div class="sphinx-tabs docutils container">
<div class="ui top attached tabular menu sphinx-menu docutils container">
<div class="active item sphinx-data-tab-VWJ1bnR1IDIwLjA0IExUUyBhbmQgbGF0ZXI= docutils container">
<div class="docutils container">
<p>Ubuntu 20.04 LTS and later</p>
</div>
</div>
<div class="item sphinx-data-tab-TWFjT1MsIFVidW50dSAxOC4wNCBMVFMgYW5kIGVhcmxpZXI= docutils container">
<div class="docutils container">
<p>MacOS, Ubuntu 18.04 LTS and earlier</p>
</div>
</div>
</div>
<div class="ui bottom attached sphinx-tab tab segment code-tab sphinx-data-tab-VWJ1bnR1IDIwLjA0IExUUyBhbmQgbGF0ZXI= active docutils container">
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> apt install kconfig-frontends
</pre></div>
</div>
</div>
<div class="ui bottom attached sphinx-tab tab segment code-tab sphinx-data-tab-TWFjT1MsIFVidW50dSAxOC4wNCBMVFMgYW5kIGVhcmxpZXI= docutils container">
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> <span class="nb">cd</span> tools/kconfig-frontends
<span class="gp">$</span> <span class="c1"># on MacOS do the following:</span>
<span class="gp">$</span> patch &lt; ../kconfig-macos.diff -p <span class="m">1</span>
<span class="gp">$</span> ./configure --enable-mconf --disable-shared --enable-static --disable-gconf --disable-qconf --disable-nconf
<span class="gp">$</span> <span class="c1"># on Linux do the following:</span>
<span class="gp">$</span> ./configure --enable-mconf --disable-nconf --disable-gconf --disable-qconf
<span class="gp">$</span> make
<span class="gp">$</span> make install
</pre></div>
</div>
</div>
</div>
</li>
<li><p>List Possible Apache NuttX Base Configurations</p>
<p>Find your hardware and a good starting application in the list of base configurations. In the application list,
<code class="docutils literal notranslate"><span class="pre">nsh</span></code> is the Apache NuttX Shell, an interactive commandline that’s a good starting place if you’re new.</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ <span class="nb">cd</span> nuttx
$ ./tools/configure.sh -L <span class="p">|</span> less
</pre></div>
</div>
</li>
<li><p>Initialize Configuration</p>
<p>Pick one of the board:application base configuration pairs from the list, and feed it to
the configuration script. The <code class="docutils literal notranslate"><span class="pre">-l</span></code> tells us that we’re on Linux. macOS and Windows builds
are possible, this guide doesn’t cover them yet.</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ <span class="nb">cd</span> nuttx
$ ./tools/configure.sh -l &lt;board-name&gt;:&lt;config-dir&gt;
<span class="c1"># for instance:</span>
$ ./tools/configure.sh -l sama5d27-xult:nsh
</pre></div>
</div>
</li>
<li><p>Customize Your Configuration (Optional)</p>
<p>This step is optional. Right now, this is mainly to get familiar with how it works– you don’t need to change
any of the options now, but knowing how to do this will come in handy later.</p>
<p>There are a lot of options. We’ll cover a few of them here. Don’t worry about the complexity– you don’t have to use most of the options.</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ make menuconfig
</pre></div>
</div>
<p>Use your arrows to navigate the menu and <kbd class="kbd docutils literal notranslate">Enter</kbd> key to enable/disable options. To exit and save your configuration, go back to the main menu, choose <code class="docutils literal notranslate"><span class="pre">&lt;Exit&gt;</span></code> and select “yes” when asked if you want to save.</p>
</li>
<li><p>Compile Apache NuttX</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ make
</pre></div>
</div>
</li>
<li><p>Install the Executable Program on Your Board</p>
<p>This step is a bit more complicated, depending on your board. It’s covered in the section
<a class="reference internal" href="running.html#running"><span class="std std-ref">Running Apache NuttX</span></a>.</p>
</li>
</ol>
<hr class="docutils" />
<p class="rubric">More Details</p>
<p>If you want more details, start at <a class="reference internal" href="install.html#install"><span class="std std-ref">Installing</span></a>.</p>
</div>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>
&copy; Copyright 2020, The Apache Software Foundation
</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>