blob: 482e9c860cab13d46008ffc14c548a194428d0ed [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>Installing &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="Compiling" href="compiling.html" />
<link rel="prev" title="Quickstart" href="quickstart.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"><a class="reference internal" href="quickstart.html">Quickstart</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Installing</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#prerequisites">Prerequisites</a></li>
<li class="toctree-l3"><a class="reference internal" href="#install-a-cross-compiler-toolchain">Install a Cross-Compiler Toolchain</a></li>
<li class="toctree-l3"><a class="reference internal" href="#get-source-code">Get Source Code</a></li>
</ul>
</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>Installing</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/quickstart/install.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="installing">
<span id="install"></span><h1>Installing<a class="headerlink" href="#installing" title="Permalink to this headline"></a></h1>
<p>To start developing on Apache NuttX, we need to get the source code, configure it, compile it, and get it uploaded onto an
embedded computing board. These instructions are for <a class="reference external" href="https://ubuntu.com/">Ubuntu</a> Linux and macOS Catalina. If you’re using a different
version, you may need to change some of the commands.</p>
<div class="section" id="prerequisites">
<h2>Prerequisites<a class="headerlink" href="#prerequisites" title="Permalink to this headline"></a></h2>
<div class="sphinx-tabs docutils container">
<div class="ui top attached tabular menu sphinx-menu docutils container">
<div class="active item sphinx-data-tab-0-0 docutils container">
<div class="docutils container">
<p>Linux</p>
</div>
</div>
<div class="item sphinx-data-tab-0-1 docutils container">
<div class="docutils container">
<p>macOS</p>
</div>
</div>
<div class="item sphinx-data-tab-0-2 docutils container">
<div class="docutils container">
<p>Windows / WSL</p>
</div>
</div>
<div class="item sphinx-data-tab-0-3 docutils container">
<div class="docutils container">
<p>Windows/Cygwin</p>
</div>
</div>
</div>
<div class="ui bottom attached sphinx-tab tab segment sphinx-data-tab-0-0 active docutils container">
<ol class="arabic simple">
<li><p>Install system packages</p></li>
</ol>
<blockquote>
<div><div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> sudo apt install <span class="se">\</span>
bison flex gettext texinfo libncurses5-dev libncursesw5-dev <span class="se">\</span>
gperf automake libtool pkg-config build-essential gperf genromfs <span class="se">\</span>
libgmp-dev libmpc-dev libmpfr-dev libisl-dev binutils-dev libelf-dev <span class="se">\</span>
libexpat-dev gcc-multilib g++-multilib picocom u-boot-tools util-linux
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple">
<li><p>Give yourself access to the serial console device</p></li>
</ol>
<blockquote>
<div><p>This is done by adding your Linux user to the <code class="docutils literal notranslate"><span class="pre">dialout</span></code> group:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> sudo usermod -a -G dialout <span class="nv">$USER</span>
<span class="gp">$</span> <span class="c1"># now get a login shell that knows we&#39;re in the dialout group:</span>
<span class="gp">$</span> su - <span class="nv">$USER</span>
</pre></div>
</div>
</div></blockquote>
</div>
<div class="ui bottom attached sphinx-tab tab segment sphinx-data-tab-0-1 docutils container">
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> brew install x86_64-elf-gcc <span class="c1"># Used by simulator</span>
<span class="gp">$</span> brew install u-boot-tools <span class="c1"># Some platform integrate with u-boot</span>
</pre></div>
</div>
</div>
<div class="ui bottom attached sphinx-tab tab segment sphinx-data-tab-0-2 docutils container">
<p>If you are are building Apache NuttX on windows and using WSL follow
that installation guide for Linux. This has been verified against the
Ubunutu 18.04 version.</p>
<p>There may be complications interacting with
programming tools over USB. Recently support for USBIP was added to WSL 2
which has been used with the STM32 platform, but it is not trivial to configure:
<a class="reference external" href="https://github.com/rpasek/usbip-wsl2-instructions">https://github.com/rpasek/usbip-wsl2-instructions</a></p>
</div>
<div class="ui bottom attached sphinx-tab tab segment sphinx-data-tab-0-3 docutils container">
<p>Download and install <a class="reference external" href="https://www.cygwin.com/">Cygwin</a> using the minimal
installation in addition to these packages:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>make bison libmpc-devel
gcc-core byacc automake-1.15
gcc-g++ gperf libncurses-devel
flex gdb libmpfr-devel
git unzip zlib-devel
</pre></div>
</div>
</div>
</div>
<p>To complete the installation of prerequisites, you need to install <cite>kconfig-frontends</cite>
as instructed in the <a class="reference internal" href="quickstart.html"><span class="doc">Quickstart</span></a> guide.</p>
</div>
<div class="section" id="install-a-cross-compiler-toolchain">
<h2>Install a Cross-Compiler Toolchain<a class="headerlink" href="#install-a-cross-compiler-toolchain" title="Permalink to this headline"></a></h2>
<p>To build Apache NuttX you need the appropriate toolchain
according to your target platform. Some Operating Systems
such as Linux distribute toolchains for various architectures.
This is usually an easy choice however you should be aware
that in some cases the version offered by your OS may have
problems and it may better to use a widely used build from
another source.</p>
<p>The following example shows how to install a toolchain for
ARM architecture:</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-VWJ1bnR1IChkZWIp docutils container">
<div class="docutils container">
<p>Ubuntu (deb)</p>
</div>
</div>
<div class="item sphinx-data-tab-1-0 docutils container">
<div class="docutils container">
<p>From arm.com</p>
</div>
</div>
</div>
<div class="ui bottom attached sphinx-tab tab segment code-tab sphinx-data-tab-VWJ1bnR1IChkZWIp active docutils container">
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> apt install gcc-arm-none-eabi binutils-arm-none-eabi
</pre></div>
</div>
</div>
<div class="ui bottom attached sphinx-tab tab segment sphinx-data-tab-1-0 docutils container">
<p>First, create a directory to hold the toolchain:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> usermod -a -G users <span class="nv">$USER</span>
<span class="gp">$</span> <span class="c1"># get a login shell that knows we&#39;re in this group:</span>
<span class="gp">$</span> su - <span class="nv">$USER</span>
<span class="gp">$</span> sudo mkdir /opt/gcc
<span class="gp">$</span> sudo chgrp -R users /opt/gcc
<span class="gp">$</span> sudo chmod -R u+rw /opt/gcc
<span class="gp">$</span> <span class="nb">cd</span> /opt/gcc
</pre></div>
</div>
<p>Download and extract toolchain:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> <span class="nv">HOST_PLATFORM</span><span class="o">=</span>x86_64-linux <span class="c1"># use &quot;mac&quot; for macOS.</span>
<span class="gp">$</span> <span class="c1"># For windows there is a zip instead (gcc-arm-none-eabi-9-2019-q4-major-win32.zip)</span>
<span class="gp">$</span> wget https://developer.arm.com/-/media/Files/downloads/gnu-rm/9-2019q4/gcc-arm-none-eabi-9-2019-q4-major-<span class="si">${</span><span class="nv">HOST_PLATFORM</span><span class="si">}</span>.tar.bz2
<span class="gp">$</span> tar xf gcc-arm-none-eabi-9-2019-q4-major-<span class="si">${</span><span class="nv">HOST_PLATFORM</span><span class="si">}</span>.tar.bz2
</pre></div>
</div>
<p>Add the toolchain to your <cite>PATH</cite>:</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>You can edit your shell’s rc files if you don’t use bash.</p>
</div>
</div>
<div class="admonition tip">
<p class="admonition-title">Tip</p>
<p>There are hints on how to get the latest tool chains for most supported
architectures in the Apache NuttX CI helper
<a class="reference external" href="https://github.com/apache/incubator-nuttx-testing/blob/master/cibuild.sh">script</a>
and Docker <a class="reference external" href="https://github.com/apache/incubator-nuttx-testing/blob/master/docker/linux/Dockerfile">container</a></p>
</div>
</div>
<div class="section" id="get-source-code">
<h2>Get Source Code<a class="headerlink" href="#get-source-code" title="Permalink to this headline"></a></h2>
<p>Now that all required tools are installed, you need to download NuttX source-code.</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-2-0 docutils container">
<div class="docutils container">
<p>Development (Git)</p>
</div>
</div>
<div class="item sphinx-data-tab-2-1 docutils container">
<div class="docutils container">
<p>Stable Release</p>
</div>
</div>
</div>
<div class="ui bottom attached sphinx-tab tab segment sphinx-data-tab-2-0 active docutils container">
<p>Apache NuttX is <a class="reference external" href="https://github.com/apache/incubator-nuttx/">actively developed on GitHub</a>.
If you intend to contribute changes or you simply need the absolute latest version,
you should clone the Git repositories:</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
</pre></div>
</div>
<p>The development source code is also available as a compressed archive, should you need it:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> curl -OL https://github.com/apache/incubator-nuttx/tarball/master
<span class="gp">$</span> curl -OL https://github.com/apache/incubator-nuttx-apps/tarball/master
<span class="gp">#</span> optionally, zipball is also available <span class="o">(</span><span class="k">for</span> Windows users<span class="o">)</span>.
</pre></div>
</div>
</div>
<div class="ui bottom attached sphinx-tab tab segment sphinx-data-tab-2-1 docutils container">
<p>Apache NuttX releases are published on the project <a class="reference external" href="https://nuttx.apache.org/download/">Downloads</a>
page and distributed by the Apache mirrors. Be sure to download both the <cite>nuttx</cite> and <cite>apps</cite> tarballs.</p>
</div>
</div>
<hr class="docutils" />
<p>Next up is <a class="reference internal" href="compiling.html#compiling"><span class="std std-ref">Compiling</span></a>.</p>
</div>
</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>