doc/getting_started/getting_started.rst - third_party/github/zephyrproject-rtos/zephyr - Git at Google

 .. _getting_started:

 Getting Started Guide
 #####################

 Use this guide to get started with your :ref:`Zephyr <introducing_zephyr>`
 development.

 Set Up the Development Environment
 **********************************

 The Zephyr project supports these operating systems:

 * Linux
 * macOS
 * Windows 8.1

 Use the following procedures to create a new development environment.

 .. toctree::
    :maxdepth: 1

    installation_linux.rst
    installation_mac.rst
    installation_win.rst


 Checking Out the Source Code Anonymously
 ========================================

 The code is hosted in a GitHub repo that supports
 anonymous cloning via git.

 To clone the repository anonymously, enter:

 .. code-block:: console

    $ git clone https://github.com/zephyrproject-rtos/zephyr.git

 You have successfully checked out a copy of the source code to your local
 machine.

 .. _getting_started_run_sample:

 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 macOS 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=<sdk installation directory>

 #. Navigate to the main project directory:

    .. code-block:: console

       $ cd zephyr

 #. Source the project environment file to set the project environment
    variables:

    .. code-block:: console

       $ source zephyr-env.sh

 #. Build the :ref:`hello_world` example for the `arduino_101` board, enter:

    .. zephyr-app-commands::
       :zephyr-app: samples/hello_world
       :board: arduino_101
       :build-dir: arduino_101
       :goals: build

 You can build for a different board by defining the variable BOARD
 with another of the supported boards, for example:

    .. zephyr-app-commands::
       :zephyr-app: samples/hello_world
       :board: arduino_due
       :build-dir: arduino_due
       :goals: build

 For further information on the supported boards go see
 :ref:`here <boards>`. Alternatively, run the following command to obtain a list
 of the supported boards:

 .. code-block:: console

    $ make usage

 Sample projects for different features of the project are available at
 at :file:`$ZEPHYR_BASE/samples`.
 After building an application successfully, the results can be found in the
 directory where cmake was invoked.

 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 boards used.


 .. _sdkless_builds:

 Building without the Zephyr SDK
 ===============================

 The Zephyr SDK is provided for convenience and ease of use. It provides
 cross-compilers for all ports supported by the Zephyr OS and does not require
 any extra flags when building applications or running tests.

 In addition to cross-compilers, the Zephyr SDK also provides prebuilt
 host tools. To use the SDK host tools alongside a custom or 3rd party
 cross-compiler, keep the ZEPHYR_SDK_INSTALL_DIR environment variable
 set to the Zephyr SDK installation directory.

 To build without the Zephyr SDK's prebuilt host tools, the
 ZEPHYR_SDK_INSTALL_DIR environment variable must be unset, the host
 tools must be built and added to path, and a 3rd party cross-compiler
 must be installed.

 #. Follow the steps below to build without the Zephyr SDK:

    .. code-block:: console

       $ unset ZEPHYR_GCC_VARIANT
       $ unset ZEPHYR_SDK_INSTALL_DIR
       $ cd <zephyr git clone location>
       $ source zephyr-env.sh

 #. Build Kconfig in :file:`$ZEPHYR_BASE/build` and add it to path

    .. code-block:: console

       $ cd $ZEPHYR_BASE
       $ mkdir build && cd build
       $ cmake $ZEPHYR_BASE/scripts
       $ make
       $ echo "export PATH=$PWD/kconfig:\$PATH" >> $HOME/.zephyrrc
       $ source $ZEPHYR_BASE/zephyr-env.sh

    .. note::

       You only need to do this once after cloning the git repository.

 Now that the host tools are installed, a 3rd party cross compiler must
 be installed. See :ref:`below <third_party_x_compilers>` for
 installing a cross compiler.

 .. _third_party_x_compilers:

 Using Custom and 3rd Party Cross Compilers
 ==========================================

 To use a 3rd party cross compiler that is not provided by the Zephyr
 SDK, follow the steps below. It is possible to use a 3rd party cross
 compiler and still use the Zephyr SDK's host tools. See :ref:`the
 section above <sdkless_builds>` for details.

 #. We will use the `GCC ARM Embedded`_ compiler for this example, download the
    package suitable for your operating system from the `GCC ARM Embedded`_ website
    and extract it on your file system. This example assumes the compiler was
    extracted to: :file:`~/gcc-arm-none-eabi-5_3-2016q1/`.

 #. Build the example :ref:`hello_world` project, enter:

    .. code-block:: console

       $ export GCCARMEMB_TOOLCHAIN_PATH="~/gcc-arm-none-eabi-5_3-2016q1/"
       $ export ZEPHYR_GCC_VARIANT=gccarmemb

    .. zephyr-app-commands::
       :zephyr-app: samples/hello_world
       :board: arduino_due
       :goals: build

 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

    $ cd $ZEPHYR_BASE/samples/hello_world
    $ mkdir qemu_build && cd qemu_build
    $ cmake -DBOARD=qemu_x86 ..
    $ make run

 To run an application using the ARM qemu_cortex_m3 board configuration
 specify the qemu_cortex_m3 board instead.

 QEMU is not supported on all boards and SoCs. 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.


 .. _GCC ARM Embedded: https://launchpad.net/gcc-arm-embedded
	.. _getting_started:

	Getting Started Guide
	#####################

	Use this guide to get started with your :ref:`Zephyr <introducing_zephyr>`
	development.

	Set Up the Development Environment
	**********************************

	The Zephyr project supports these operating systems:

	* Linux
	* macOS
	* Windows 8.1

	Use the following procedures to create a new development environment.

	.. toctree::
	:maxdepth: 1

	installation_linux.rst
	installation_mac.rst
	installation_win.rst


	Checking Out the Source Code Anonymously
	========================================

	The code is hosted in a GitHub repo that supports
	anonymous cloning via git.

	To clone the repository anonymously, enter:

	.. code-block:: console

	$ git clone https://github.com/zephyrproject-rtos/zephyr.git

	You have successfully checked out a copy of the source code to your local
	machine.

	.. _getting_started_run_sample:

	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 macOS 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=<sdk installation directory>

	#. Navigate to the main project directory:

	.. code-block:: console

	$ cd zephyr

	#. Source the project environment file to set the project environment
	variables:

	.. code-block:: console

	$ source zephyr-env.sh

	#. Build the :ref:`hello_world` example for the `arduino_101` board, enter:

	.. zephyr-app-commands::
	:zephyr-app: samples/hello_world
	:board: arduino_101
	:build-dir: arduino_101
	:goals: build

	You can build for a different board by defining the variable BOARD
	with another of the supported boards, for example:

	.. zephyr-app-commands::
	:zephyr-app: samples/hello_world
	:board: arduino_due
	:build-dir: arduino_due
	:goals: build

	For further information on the supported boards go see
	:ref:`here <boards>`. Alternatively, run the following command to obtain a list
	of the supported boards:

	.. code-block:: console

	$ make usage

	Sample projects for different features of the project are available at
	at :file:`$ZEPHYR_BASE/samples`.
	After building an application successfully, the results can be found in the
	directory where cmake was invoked.

	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 boards used.


	.. _sdkless_builds:

	Building without the Zephyr SDK
	===============================

	The Zephyr SDK is provided for convenience and ease of use. It provides
	cross-compilers for all ports supported by the Zephyr OS and does not require
	any extra flags when building applications or running tests.

	In addition to cross-compilers, the Zephyr SDK also provides prebuilt
	host tools. To use the SDK host tools alongside a custom or 3rd party
	cross-compiler, keep the ZEPHYR_SDK_INSTALL_DIR environment variable
	set to the Zephyr SDK installation directory.

	To build without the Zephyr SDK's prebuilt host tools, the
	ZEPHYR_SDK_INSTALL_DIR environment variable must be unset, the host
	tools must be built and added to path, and a 3rd party cross-compiler
	must be installed.

	#. Follow the steps below to build without the Zephyr SDK:

	.. code-block:: console

	$ unset ZEPHYR_GCC_VARIANT
	$ unset ZEPHYR_SDK_INSTALL_DIR
	$ cd <zephyr git clone location>
	$ source zephyr-env.sh

	#. Build Kconfig in :file:`$ZEPHYR_BASE/build` and add it to path

	.. code-block:: console

	$ cd $ZEPHYR_BASE
	$ mkdir build && cd build
	$ cmake $ZEPHYR_BASE/scripts
	$ make
	$ echo "export PATH=$PWD/kconfig:\$PATH" >> $HOME/.zephyrrc
	$ source $ZEPHYR_BASE/zephyr-env.sh

	.. note::

	You only need to do this once after cloning the git repository.

	Now that the host tools are installed, a 3rd party cross compiler must
	be installed. See :ref:`below <third_party_x_compilers>` for
	installing a cross compiler.

	.. _third_party_x_compilers:

	Using Custom and 3rd Party Cross Compilers
	==========================================

	To use a 3rd party cross compiler that is not provided by the Zephyr
	SDK, follow the steps below. It is possible to use a 3rd party cross
	compiler and still use the Zephyr SDK's host tools. See :ref:`the
	section above <sdkless_builds>` for details.

	#. We will use the `GCC ARM Embedded`_ compiler for this example, download the
	package suitable for your operating system from the `GCC ARM Embedded`_ website
	and extract it on your file system. This example assumes the compiler was
	extracted to: :file:`~/gcc-arm-none-eabi-5_3-2016q1/`.

	#. Build the example :ref:`hello_world` project, enter:

	.. code-block:: console

	$ export GCCARMEMB_TOOLCHAIN_PATH="~/gcc-arm-none-eabi-5_3-2016q1/"
	$ export ZEPHYR_GCC_VARIANT=gccarmemb

	.. zephyr-app-commands::
	:zephyr-app: samples/hello_world
	:board: arduino_due
	:goals: build

	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

	$ cd $ZEPHYR_BASE/samples/hello_world
	$ mkdir qemu_build && cd qemu_build
	$ cmake -DBOARD=qemu_x86 ..
	$ make run

	To run an application using the ARM qemu_cortex_m3 board configuration
	specify the qemu_cortex_m3 board instead.

	QEMU is not supported on all boards and SoCs. 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.


	.. _GCC ARM Embedded: https://launchpad.net/gcc-arm-embedded