michaelh/zephyr
1
0
Fork 0
Code Releases Activity

docs: Getting Started overhaul

Browse source 
- Put everything in one page and simplify workflow.
- Fix indent and layout

Change-Id: Ifd9d11531c9b906324cf87cf401cbce416cc01a4
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
This commit is contained in:
Anas Nashif 2016-02-13 07:41:34 -05:00 • committed by Anas Nashif
commit d0c5eaf4a0
6 changed files with 159 additions and 267 deletions
Download patch file Download diff file Expand all files Collapse all files

94
doc/getting_started/building_zephyr.rst
View file

@ -1,94 +0,0 @@
.. _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.
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/hello_world/microkernel
$ 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` with each sample having a microkernel
and nanokernel specific build.
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 emulation board configuration (qemu_x86), type:
.. code-block:: console
$ make BOARD=qemu_x86 qemu
To run an application using the ARM qemu_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
View file

@ -1,27 +0,0 @@
.. _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:`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:`kernel` 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.

148
doc/getting_started/getting_started.rst
View file

@ -3,19 +3,147 @@
Getting Started Guide Getting Started Guide
##################### #####################
Use this guide to get started with your Zephyr development. We have collected Use this guide to get started with your Zephyr development.
all procedures you will need in three basic steps:
Set Up the Development Environment
**********************************
The Zephyr project supports these operating systems:
* Linux
* Mac OS
* Windows 8.1
Use the following procedures to create a new development environment.
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 1
setting_up.rst installation_linux.rst
developing.rst installation_mac.rst
building_zephyr.rst installation_win.rst
Configuring Network and Proxies
*******************************
Setting up your Zephyr development requires Internet access. Verify that Checking Out the Source Code Anonymously
console commands can be run as both user and administrator and that access to ========================================
the Internet is not impeded by a firewall.
The code is hosted at the Linux Foundation with a Gerrit backend that supports
anonymous cloning via git.
To clone the repository anonymously, enter:
.. code-block:: console
$ git clone https://gerrit.zephyrproject.org/r/zephyr zephyr-project
You have successfully checked out a copy of the source code to your local
machine.
Once you're ready to start contributing, follow the steps to make yourself
a Linux Foundation account at :ref:`gerrit_accounts`.
Building and Running an Application
***********************************
Using the 'Hello World' sample application as a base model, the following
section will describe the pieces necessary for creating a Zephyr 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:
#. Make sure your environment is setup by exporting the following environment
variables. When using the Zephyr SDK on Linux for example, type:
.. code-block:: console
$ export ZEPHYR_GCC_VARIANT=zephyr
$ export ZEPHYR_SDK_INSTALL_DIR=/opt/zephyr-sdk
#. 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
#. Build the example project, enter:
.. code-block:: console
$ cd $ZEPHYR_BASE/samples/hello_world/microkernel
$ 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 board by defining the variable BOARD with one of the
supported boards, for example:
.. code-block:: console
$ make BOARD=arduino_101
For further information on the supported boards go see
:ref:`here <board>`. Alternatively, run the following command to obtain a list
of the supported boards:
.. code-block:: console
$ make help
The sample projects for the microkernel and the nanokernel are available
at :file:`$ZEPHYR_BASE/samples`.
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 application configuration
The build system generates different names for different use cases depending on
the hardware and platforms used.
Running a Sample Application in QEMU
====================================
To perform rapid testing of an application in the development environment you
can use the qemu emulation board configuration available for both X86 and ARM
Cortex-M3 architectures. This can be easily accomplished by calling a special
target when building an application that invokes QEMU once the build process is
completed.
To run an application using the x86 emulation board configuration (qemu_x86),
type:
.. code-block:: console
$ make BOARD=qemu_x86 qemu
To run an application using the ARM qemu_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. 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.
.. _Linux Foundation ID website: https://identity.linuxfoundation.org
.. _Gerrit: https://gerrit.zephyrproject.org/

74
doc/getting_started/installation_linux.rst
View file

@ -46,10 +46,6 @@ Install the following with either apt-get or dnf.
Minor version updates of the listed required packages might also Minor version updates of the listed required packages might also
work. 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: Install the required packages in a Ubuntu host system with:
.. code-block:: console .. code-block:: console
@ -69,24 +65,6 @@ Install the required packages in a Fedora host system with:
Ensure that at least the 32 bit versions of the packages are installed. Ensure that at least the 32 bit versions of the packages are installed.
Ideally, both the 32 and 64 bit versions should be 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: .. _zephyr_sdk:
Installing the Zephyr Software Development Kit Installing the Zephyr Software Development Kit
@ -114,7 +92,7 @@ Follow these steps to install the SDK on your Linux host system.
Alternatively, you can use the following command to download the desired Alternatively, you can use the following command to download the desired
version: version:
.. code-block:: console .. code-block:: console
$ wget https://nexus.zephyrproject.org/content/repositories/releases/org/zephyrproject/zephyr-sdk/<version>-i686/zephyr-sdk-<version>-i686-setup.run $ wget https://nexus.zephyrproject.org/content/repositories/releases/org/zephyrproject/zephyr-sdk/<version>-i686/zephyr-sdk-<version>-i686-setup.run
@ -123,60 +101,26 @@ Follow these steps to install the SDK on your Linux host system.
#. Run the installation binary, follow this example: #. Run the installation binary, follow this example:
.. code-block:: console .. code-block:: console
$ chmod +x zephyr-sdk-<version>-i686-setup.run $ chmod +x zephyr-sdk-<version>-i686-setup.run
$ sudo ./zephyr-sdk-<version>-i686-setup.run $ sudo ./zephyr-sdk-<version>-i686-setup.run
.. note:: There is no need for `sudo` if the SDK is installed in the current
Replace <version> with the version number of the SDK that you downloaded. user's home directory.
.. 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 #. Follow the installation instructions on the screen. The
toolchain's default installation location is :file:`/opt/zephyr-sdk/`. 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 #. To use the Zephyr SDK, export the following environment variables and
use the target location where SDK was installed, type: use the target location where SDK was installed, type:
.. code-block:: console .. code-block:: console
$ export ZEPHYR_GCC_VARIANT=zephyr $ export ZEPHYR_GCC_VARIANT=zephyr
$ export ZEPHYR_SDK_INSTALL_DIR=/opt/zephyr-sdk $ export ZEPHYR_SDK_INSTALL_DIR=<sdk installation directory>
To use the same toolchain in new sessions in the future you can set the To use the same toolchain in new sessions in the future you can set the
variables in the file :file:`${HOME}/.zephyrrc`, for example: variables in the file :file:`${HOME}/.zephyrrc`, for example:

19
doc/getting_started/installation_mac.rst
View file

@ -8,12 +8,19 @@ 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 After completing these steps, you will be able to compile and run your Zephyr
applications on the following Mac OS version: applications on the following Mac OS version:
Mac OS X 10.11 (El Capitan) * Mac OS X 10.11 (El Capitan)
Update Your Operating System .. _mac_network_configuration:
****************************
Before proceeding with the build, ensure your OS is up to date. 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.
.. _mac_requirements: .. _mac_requirements:
@ -28,9 +35,7 @@ build for and install tools that the build system requires.
Minor version updates of the listed required packages might also Minor version updates of the listed required packages might also
work. work.
.. attention:: Before proceeding with the build, ensure your OS is up to date.
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 First, install the :program:`Homebrew` (The missing package manager for
OS X). Homebrew is a free and open-source software package management system OS X). Homebrew is a free and open-source software package management system

64
doc/getting_started/setting_up.rst
View file

@ -1,64 +0,0 @@
.. _setting_up:
Setting Up for Zephyr Development
#################################
Setting up your development environment for Zephyr is done in two steps:
1. Downloading the code
2. Set up the development environment
Download the Code
*****************
The code is hosted at the Linux Foundation with a Gerrit backend that supports
anonymous cloning via GIT.
Checking Out the Source Code
============================
#. Clone the repository:
.. code-block:: console
$ git clone https://gerrit.zephyrproject.org/r/zephyr zephyr-project
You have successfully checked out a copy of the source code to your local
machine.
.. note::
Once you're ready to start contributing, follow the steps to make yourself
a Linux Foundation account at :ref:`gerrit_accounts`.
.. 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
installation_win.rst
.. _Linux Foundation ID website: https://identity.linuxfoundation.org
.. _Gerrit: https://gerrit.zephyrproject.org/