michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: Refactor the Quick Start Guide.

Browse source 
Restructured the guide to follow a basic three step process: Set up, develop,
build. All information that is independent of the OS selection was taken out of
of the OS related documents and placed in the general set up sections.

A new section, Developing Zephyr Applications, was added with links to all the
development relevant section of the documentation.

The content in local_development.rst was split between the setting_up.rst,
installation_linux.rst and installation_mac.rst files as appropriate.

This new structure provides a much better flow for developers beginning their
Zephyr develpment.

Applied all of Inaky's suggestions in the refactored content.

Minor markup fixes and language edits were also perfomed during the refactoring.

Fixed a cross-reference that was broken during the refactor.

Applied all the feedback from the first trial run.

Applied the feedback provided by David Kinder from TCS.

Change-Id: I3368a3a41ec9ad02cc4e7b37fe71c65abd8a7df9
Signed-off-by: Rodrigo Caballero <rodrigo.caballero.abraham@intel.com>
This commit is contained in:
Rodrigo Caballero 2016-01-28 10:59:49 -06:00 • committed by Anas Nashif
commit 4f976c20d7
14 changed files with 527 additions and 404 deletions
Download patch file Download diff file Expand all files Collapse all files

97
doc/getting_started/building_zephyr.rst Normal file
View file

@ -0,0 +1,97 @@
.. _building_zephyr:
Building and Running an Application
###################################
Congratulations! You have successfully set up your development environment
and created a Zephyr application. This section provides all the steps to
build a Zephyr kernel containing your application and run it. We use the
`Hello World` sample application as an example. However, the steps needed are
the same for your own application.
Building and Running an Application
***********************************
The processes to build and run a Zephyr application are the same across
operating systems. Nevertheless, the commands needed do differ from one OS to
the next. The following sections contain the commands used in a Linux
development environment. If you are using Mac OS please use the appropriate
commands for your OS.
Building a Sample Application
=============================
To build an example application follow these steps:
#. Go to the root directory of the Zephyr Project.
#. Set the environment variables on each console, see
:ref:`environment_variables`
#. Build the example project, enter:
.. code-block:: console
$ cd $ZEPHYR_BASE/samples/microkernel/apps/hello_world
$ make
The above invocation of make will build the hello_world sample application
using the default settings defined in the application's Makefile. You can
build for a different platform by defining the variable BOARD with one of the
supported platforms, for example:
.. code-block:: console
$ make BOARD=minnowboard
For further information on the supported platforms go see
:ref:`here <board>`. Alternatively, run the following command on the code
root to obtain a list of the supported platforms of a particular
architecture:
.. code-block:: console
$ make help
The sample projects for the microkernel and the nanokernel are found
at :file:`$ZEPHYR_BASE/samples/microkernel/apps` and
:file:`$ZEPHYR_BASE/samples/nanokernel/apps` respectively.
After building an application successfully, the results can be found in the
:file:`outdir` sub-directory under the application root directory.
The ELF binaries generated by the build system are named by default
:file:`zephyr.elf`. This value can be overridden in the Makefile. The build
system generates different names for different use cases depending on the
hardware and platforms used.
Running a Sample Application
============================
To perform rapid testing of an application in the development environment you
can use QEMU with some of the supported platforms and architecture. This can
be easily accomplished by calling a special target when building an
application that invokes QEMU once the build process is completed.
1. Run an application using the default board configuration, type:
.. code-block:: console
$ make qemu
To run an application using the x86 minnowboard board configuration, type:
.. code-block:: console
$ make BOARD=qemu_x86 qemu
To run an application using the ARM basic_cortex_m3 board configuration, type:
.. code-block:: console
$ make BOARD=qemu_cortex_m3 ARCH=arm qemu
QEMU is not supported on all boards and platforms. Some samples and test
cases might fail when running in the emulator. When developing for a specific
hardware target you should always test on the actual hardware and should not
rely on testing in the QEMU emulation environment only.

27
doc/getting_started/developing.rst Normal file
View file

@ -0,0 +1,27 @@
.. _developing:
Developing Zephyr Applications
##############################
After setting up you development environment you are now ready to begin
developing your own Zephyr applications. To help you on this task, we provide
you with multiple resources:
The :ref:`application` section collects all the information you need to
develop, run and build your Zephyr applications.
The :ref:`contributing_code` section collects all the project's guidelines
regarding code collaboration, code style and Gerrit use. Be sure to test your
development before submitting it to Gerrit.
The :ref:`zephyr_primer` section contains detailed information regarding
micro- and nanokernel services and their functionality.
The :ref:`api` section contains the detailed information of all the available
APIs.
The :ref:`communication` section provides all the information regarding the
project's mailing list and bug tracking system.
The :ref:`documentation` section collects the project's documentation style
guides for in-code documentation and stand alone documentation.

21
doc/getting_started/getting_started.rst Normal file
View file

@ -0,0 +1,21 @@
.. _getting_started:
Getting Started Guide
#####################
Use this guide to get started with your Zephyr development. We have collected
all procedures you will need in three basic steps:
.. toctree::
:maxdepth: 1
setting_up.rst
developing.rst
building_zephyr.rst
Configuring Network and Proxies
*******************************
Setting up your Zephyr development requires Internet access. Verify that
console commands can be run as both user and administrator and that access to
the Internet and is not impeded by a firewall.

191
doc/getting_started/installation_linux.rst Normal file
View file

@ -0,0 +1,191 @@
.. _installation_linux:
Development Environment Setup on Linux
######################################
This section describes how to set up a Linux development system.
After completing these steps, you will be able to compile and run your Zephyr
applications on the following Linux distributions:
* Ubuntu 14.04 LTS 64 bit
* Fedora 22 64 bit
Where needed, alternative instructions are listed for Ubuntu and Fedora.
Installing the Host's Operating System
**************************************
Building the project's software components including the kernel has been
tested on Ubuntu and Fedora systems. Instructions for installing these OSes
are beyond the scope of this document.
Update Your Operating System
****************************
Before proceeding with the build, ensure your OS is up to date. On Ubuntu:
.. code-block:: console
$ sudo apt-get update
On Fedora:
.. code-block:: console
$ sudo dnf update
.. _linux_network_configuration:
Configuring Network and Proxies
*******************************
Building the kernel requires the command-line tools of git, ssh, wget,
curl. Verify that each service can be run as both user and root and that access
to the Internet and is not impeded by a firewall.
If your network requires proxy access through a proxy, please configure using
steps similar git, ssh and wget in accordance to your security policies.
.. _linux_required_software:
Installing Requirements and Dependencies
****************************************
Install the following with either apt-get or dnf.
.. note::
Minor version updates of the listed required packages might also
work.
.. attention::
Check your firewall and proxy configurations to ensure that Internet
access is available before attempting to install the required packages.
Install the required packages in a Ubuntu host system with:
.. code-block:: console
$ sudo apt-get install git make gcc gcc-multilib g++ libc6-dev-i386 \
g++-multilib
Install the required packages in a Fedora host system with:
.. code-block:: console
$ sudo dnf group install "Development Tools"
$ sudo dnf install git make gcc glib-devel.i686 glib2-devel.i686 \
glibc-static libstdc++-static glibc-devel.i686
.. important::
Ensure that at least the 32 bit versions of the packages are installed.
Ideally, both the 32 and 64 bit versions should be installed.
.. _environment_variables:
Setting the Project's Environment Variables
===========================================
#. Navigate to the main project directory:
.. code-block:: console
$ cd zephyr-project
#. Source the project environment file to set the project environtment
variables:
.. code-block:: console
$ source zephyr-env.sh
.. _zephyr_sdk:
Installing the Zephyr Software Development Kit
==============================================
Zephyr's :abbr:`SDK (Software Development Kit)` contains all necessary tools
and cross-compilers needed to build the kernel on all supported
architectures. Additionally, it includes host tools such as a custom QEMU and
a host compiler for building host tools if necessary. The SDK supports the
following architectures:
* :abbr:`IA-32 (Intel Architecture 32 bits)`
* :abbr:`ARM (Advanced RISC Machines)`
* :abbr:`ARC (Argonaut RISC Core)`
Follow these steps to install the SDK on your Linux host system.
#. Download the `SDK self-extractable binary`_.
.. hint::
Visit the `Zephyr SDK archive`_ to find a list with all the available versions.
.. code-block:: console
$ wget --user=USERNAME --ask-password \ https://zephyr-
project.intel.com/public/zephyr-internal/zephyr-sdk/zephyr-
sdk-0.7.2-i686-setup.run
#. Run the installation binary, type:
.. code-block:: console
$ chmod +x zephyr-sdk-0.7.2-i686-setup.run
$ sudo ./zephyr-sdk-0.7.2-i686-setup.run
.. note::
There is no need for `sudo` if the SDK is installed in the current
user's home directory.
#. Follow the installation instructions on the screen. The
toolchain's default installation location is :file:`/opt/zephyr-sdk/`.
.. code-block:: console
Verifying archive integrity... All good.
Uncompressing SDK for Zephyr 100%
Enter target directory for SDK (default: /opt/zephyr-sdk/):
#. Enter a new location or hit :kbd:`Return` to accept default.
.. code-block:: console
Installing SDK to /opt/zephyr-sdk/
Creating directory /opt/zephyr-sdk/
Success
[*] Installing x86 tools...
[*] Installing arm tools...
[*] Installing arc tools...
...
[*] Installing additional host tools...
Success installing SDK. SDK is ready to be used.
#. To use the Zephyr SDK, export the following environment variables and
use the target location where SDK was installed, type:
.. code-block:: console
$ export ZEPHYR_GCC_VARIANT=zephyr
$ export ZEPHYR_SDK_INSTALL_DIR=/opt/zephyr-sdk
.. _SDK self-extractable binary:
https://zephyr-project.intel.com/public/zephyr-internal/zephyr-sdk/zephyr-
sdk-0.7.2-i686-setup.run
.. _Zephyr SDK archive:
https://zephyr-project.intel.com/public/zephyr-internal/zephyr-sdk/

179
doc/getting_started/installation_mac.rst Normal file
View file

@ -0,0 +1,179 @@
.. _installing_zephyr_mac:
Development Environment Setup on Mac OS
#######################################
This section describes how to set up a Mac OS development system.
After completing these steps, you will be able to compile and run your Zephyr
applications on the following Mac OS version:
Mac OS X 10.11 (El Capitan)
Update Your Operating System
****************************
Before proceeding with the build, ensure your OS is up to date.
.. _mac_requirements:
Installing Requirements and Dependencies
****************************************
To install the software components required to build the Zephyr kernel on a
Mac, you will need to build a cross compiler for the target devices you wish to
build for and install tools that the build system requires.
.. note::
Minor version updates of the listed required packages might also
work.
.. attention::
Check your firewall and proxy configurations to ensure that Internet
access is available before attempting to install the required packages.
First, install the :program:`Homebrew` (The missing package manager for
OS X). Homebrew is a free and open-source software package management system
that simplifies the installation of software on Apple's OS X operating
system.
To install :program:`Homebrew`, visit the `Homebrew site`_ and follow the
installation instructions on the site.
To complete the Homebrew installation, you might be prompted to install some
missing dependency. If so, follow please follow the instructions provided.
After Homebrew was successfully installed, install the following tools using
the brew command line.
.. code-block:: console
$ brew install gettext qemu help2man mpfr gmp coreutils wget
$ brew tap homebrew/dupes
$ brew install grep --default-names
.. code-block:: console
$ brew install crosstool-ng
Alternatively you can install the latest version of :program:`crosstool-ng`
from source. Download the latest version from the `crosstool-ng site`_. The
latest version usually supports the latest released compilers.
.. code-block:: console
$ wget
http://crosstool-ng.org/download/crosstool-ng/crosstool-ng-1.22.0.tar.bz2
$ tar xvf crosstool-ng-1.22.0.tar.bz2
$ cd crosstool-ng/
$ ./configure
$ make
$ make install
.. _setting_up_mac_toolchain:
Setting Up the Toolchain
************************
Creating a Case-sensitive File System
=====================================
Building the compiler requires a case-senstive file system. Therefore, use
:program:`diskutil` to create an 8 GB blank sparse image making sure you select
case-sensitive file system (OS X Extended (Case-sensitive, Journaled) and
mount it.
Alternatively you can use the script below to create the image:
.. code-block:: bash
#!/bin/bash ImageName=CrossToolNG ImageNameExt=${ImageName}.sparseimage
diskutil umount force /Volumes/${ImageName} && true rm -f ${ImageNameExt}
&& true hdiutil create ${ImageName} -volname ${ImageName} -type SPARSE
-size 8g -fs HFSX hdiutil mount ${ImageNameExt} cd /Volumes/$ImageName
When mounted, the file system of the image will be available under
:file:`/Volumes`. Change to the mounted directory:
.. code-block:: console
$ cd /Volumes/CrossToolNG
$ mkdir build
$ cd build
Setting the Toolchain Options
=============================
In the Zephyr kernel source tree we provide two configurations for
both ARM and X86 that can be used to pre-select the options needed
for building the toolchain.
The configuration files can be found in :file:`${ZEPHYR_BASE}/scripts/cross_compiler/`.
.. code-block:: console
$ cp ${ZEPHYR_BASE}/scripts/cross_compiler/x86.config .config
You can create a toolchain configuration or customize an existing configuration
yourself using the configuration menus:
.. code-block:: console
$ ct-ng menuconfig
Verifying the Configuration of the Toolchain
============================================
Before building the toolchain it is advisable to perform a quick verification
of the configuration set for the toolchain.
1. Open the generated :file:`.config` file.
2. Verify the following lines are present, assuming the sparse image was
mounted under :file:`/Volumes/CrossToolNG`:
.. code-block:: bash
...
CT_LOCAL_TARBALLS_DIR="/Volumes/CrossToolNG/src"
# CT_SAVE_TARBALLS is not set
CT_WORK_DIR="${CT_TOP_DIR}/.build"
CT_PREFIX_DIR="/Volumes/CrossToolNG/x-tools/${CT_TARGET}"
CT_INSTALL_DIR="${CT_PREFIX_DIR}"
...
Building the Toolchain
======================
To build the toolchain, enter:
.. code-block:: console
$ ct-ng build
The above process takes a while. When finished, the toolchain will be available
under :file:`/Volumes/CrossToolNG/x-tools`.
Repeat the step for all architectures you want to support in your environment.
To use the toolchain with Zephyr, export the following environment variables
and use the target location where the toolchain was installed, type:
.. code-block:: console
$ export ZEPHYR_GCC_VARIANT=xtools
$ export ZEPHYR_SDK_INSTALL_DIR=/Volumes/CrossToolNG/x-tools
.. _Homebrew site: http://brew.sh/
.. _crosstool-ng site: http://crosstool-ng.org

142
doc/getting_started/setting_up.rst Normal file
View file

@ -0,0 +1,142 @@
.. _setting_up:
Setting Up for Zephyr Development
#################################
Setting up your development environment for Zephyr is done in two steps:
1. Access the code
2. Set up the development environment
Access the Code
***************
Currently, the code is hosted at 01.org and code review is done using Gerrit.
Therefore, a 01.org account is needed to access the code. Follow these steps
to gain access to the code in Gerrit:
#. `Create`_ or `update`_ a `01.org`_ account.
#. Request access by contacting the Zephyr project team.
#. Once access is granted, `access Gerrit`_.
#. Log in using your 01.org account credentials.
.. _Create: https://01.org/user/register
.. _update: https://01.org/user/login
.. _access Gerrit: https://oic-review.01.org/gerrit/
.. _01.org: https://01.org/
Configuring Gerrit to Use SSH
=============================
Gerrit uses SSH to interact with your Git client. A SSH private key
needs to be generated on the development machine with a matching public
key on the Gerrit server.
If you already have a SSH key-pair, skip this section.
As an example, we provide the steps to generate the SSH key-pair on a Linux
environment. Follow the equivalent steps on your OS.
#. Create a key-pair, enter:
.. code-block:: console
$ ssh-keygen -t rsa -C "John Doe john.doe@example.com"
.. note::
This will ask you for a password to protect the private key as it
generates a unique key. Please keep this password private, and DO NOT
enter a blank password.
The generated key-pair is found in:
:file:`~/.ssh/id_rsa` and :file:`~/.ssh/id_rsa.pub`.
#. Add the private key in the :file:`id_rsa` file in your key ring:
.. code-block:: console
$ ssh-add ~/.ssh/id_rsa
Once the key-pair has been generated, the public key must be added to Gerrit.
Follow these steps to add your public key :file:`id_rsa.pub` to the Gerrit
account:
1. Go to `access Gerrit`_.
2. Click on your account name in the upper right corner.
3. From the pop-up menu, select :guilabel:`Settings`.
4. On the left side menu, click on :guilabel:`SSH Public Keys`.
5. Paste the contents of your public key :file:`~/.id/id_rsa.pub` and click
:guilabel:`Add key`.
.. note::
The :file:`id_rsa.pub` file can be opened using any text editor. Ensure
that all the contents of the file are selected, copied and pasted into the
:guilabel:`Add SSH key` window in Gerrit.
.. warning::
Potential Security Risk! Do not copy your private key
:file:`~/.ssh/id_rsa` Use only the public :file:`~/.id/id_rsa.pub`.
Gerrit Commit Message Hook
==========================
.. include:: ../collaboration/code/gerrit_practices.rst
:start-line: 42
:end-line: 49
.. _code_check_out:
Checking Out the Source Code
============================
#. Ensure that SSH has been set up properly. See
`Configuring Gerrit to Use SSH`_ for details.
#. Clone the repository:
.. code-block:: console
$ git clone
ssh://01ORGUSERNAME@oic-review.01.org:29418/forto-collab zephyr-project
You have successfully checked out a copy of the source code to your local
machine.
.. important::
Linux users need to download the Zephyr SDK even after successfully
cloning the source code. The SDK contains packages that are not part of
the Zephyr Project. See :ref:`zephyr_sdk` for details.
Set Up the Development Environment
**********************************
The Zephyr project supports these operating systems:
* Linux
* Mac OS
Follow the steps appropriate for your development system's
:abbr:`OS (Operating System)`.
Use the following procedures to create a new development environment. Given
that the file hierarchy might change from one release to another, these
instructions could not work properly in an existing development environment.
Perform the steps in the procedures in the order they appear.
.. toctree::
:maxdepth: 2
installation_linux.rst
installation_mac.rst