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.

 Checking Out the Source Code Anonymously
 ****************************************

 The Zephyr source code is hosted in a GitHub repo that supports
 anonymous cloning via git. There are scripts and such in this repo that
 you'll need to set up your development environment, and we'll be using
 Git to get this repo.  (If you don't have Git installed, see the
 beginning of the OS-specific instructions below for help.)

 We'll begin by
 using Git to clone the repository anonymously. Enter:

 .. code-block:: console

    # On Linux/macOS
    cd ~
    # On Windows
    cd %userprofile%

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

 You have successfully checked out a copy of the source code to your local
 machine in the ~/zephyr folder.

 .. _getting_started_cmake:

 A brief note on the Zephyr build system
 ***************************************

 The Zephyr project uses `CMake`_ as a tool for managing the building of the
 project. CMake is able to generate build files in different formats (also
 known as "generators"), and the following ones are currently supported
 by Zephyr:

  * ``make``: Supported on UNIX-like platforms (Linux, macOS).
  * ``ninja``: Supported on all platforms.

 Most of the examples in the Zephyr documentation use `ninja` as a build tool
 but you should be able to use any generator on any of the examples listed.

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

 The Zephyr project supports these operating systems:

 * Linux
 * macOS
 * Microsoft Windows

 Use the following procedures to create a new development environment.

 .. toctree::
    :maxdepth: 1

    installation_linux.rst
    installation_mac.rst
    installation_win.rst


 .. _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


       # On Linux/macOS
       export ZEPHYR_GCC_VARIANT=zephyr
       export ZEPHYR_SDK_INSTALL_DIR=<sdk installation directory>
       # On Windows
       set ZEPHYR_GCC_VARIANT=zephyr
       set ZEPHYR_SDK_INSTALL_DIR=<sdk installation directory>

 #. Navigate to the main project directory:

    .. code-block:: console

       cd zephyr

 #. Set the project environment variables:

    .. code-block:: console

       # On Linux/macOS
       source zephyr-env.sh
       # On Windows
       set ZEPHYR_BASE=%cd%

 #. 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

    On Linux/macOS you can also build with ``make`` instead of ``ninja``:

    .. zephyr-app-commands::
       :zephyr-app: samples/hello_world
       :generator: make
       :host-os: unix
       :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

    ninja 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

       # On Linux/macOS
       unset ZEPHYR_GCC_VARIANT
       unset ZEPHYR_SDK_INSTALL_DIR
       cd <zephyr git clone location>
       source zephyr-env.sh
       # On Windows
       set ZEPHYR_GCC_VARIANT=
       set ZEPHYR_SDK_INSTALL_DIR=
       cd <zephyr git clone location>
       set ZEPHYR_BASE=%cd%


 #. On UNIX platforms, 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 `Using Custom and 3rd Party Cross Compilers`_ for
 details.

 .. _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 `Building
 without the Zephyr SDK`_ 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:`<user folder>/gcc-arm-none-eabi-5_3-2016q1/`.

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

    .. code-block:: console

       # On Linux/macOS
       export GCCARMEMB_TOOLCHAIN_PATH="~/gcc-arm-none-eabi-5_3-2016q1/"
       export ZEPHYR_GCC_VARIANT=gccarmemb
       # On Windows
       set GCCARMEMB_TOOLCHAIN_PATH="%userprofile%\gcc-arm-none-eabi-5_3-2016q1\"
       set 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:

 .. zephyr-app-commands::
    :zephyr-app: samples/hello_world
    :host-os: unix
    :board: qemu_x86
    :goals: build run

 To exit the qemu emulator, press ``Ctrl-a``, followed by ``x``.

 Use the ``qemu_cortex_m3`` board configuration to test the ARM build.

 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.

 Running a Sample Application natively (POSIX OS)
 ================================================

 It is also possible to compile some of the sample and test applications to run
 as native process on a POSIX OS (e.g. Linux).
 To be able to do this, remember to have installed the 32 bit libC if your OS is
 natively 64bit.

 To compile and run an application in this way, type:

 .. zephyr-app-commands::
    :zephyr-app: samples/hello_world
    :host-os: unix
    :board: native_posix
    :goals: build

 and then:

 .. code-block:: console

    ninja run
    # or just:
    zephyr/zephyr.exe
    # Press Ctrl+C to exit

 This executable can be instrumented like any other Linux process. For ex. with gdb
 or valgrind.
 Note that the native port is currently only tested in Linux.

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

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

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

	Checking Out the Source Code Anonymously
	****************************************

	The Zephyr source code is hosted in a GitHub repo that supports
	anonymous cloning via git. There are scripts and such in this repo that
	you'll need to set up your development environment, and we'll be using
	Git to get this repo. (If you don't have Git installed, see the
	beginning of the OS-specific instructions below for help.)

	We'll begin by
	using Git to clone the repository anonymously. Enter:

	.. code-block:: console

	# On Linux/macOS
	cd ~
	# On Windows
	cd %userprofile%

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

	You have successfully checked out a copy of the source code to your local
	machine in the ~/zephyr folder.

	.. _getting_started_cmake:

	A brief note on the Zephyr build system
	***************************************

	The Zephyr project uses `CMake`_ as a tool for managing the building of the
	project. CMake is able to generate build files in different formats (also
	known as "generators"), and the following ones are currently supported
	by Zephyr:

	* ``make``: Supported on UNIX-like platforms (Linux, macOS).
	* ``ninja``: Supported on all platforms.

	Most of the examples in the Zephyr documentation use `ninja` as a build tool
	but you should be able to use any generator on any of the examples listed.

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

	The Zephyr project supports these operating systems:

	* Linux
	* macOS
	* Microsoft Windows

	Use the following procedures to create a new development environment.

	.. toctree::
	:maxdepth: 1

	installation_linux.rst
	installation_mac.rst
	installation_win.rst


	.. _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


	# On Linux/macOS
	export ZEPHYR_GCC_VARIANT=zephyr
	export ZEPHYR_SDK_INSTALL_DIR=<sdk installation directory>
	# On Windows
	set ZEPHYR_GCC_VARIANT=zephyr
	set ZEPHYR_SDK_INSTALL_DIR=<sdk installation directory>

	#. Navigate to the main project directory:

	.. code-block:: console

	cd zephyr

	#. Set the project environment variables:

	.. code-block:: console

	# On Linux/macOS
	source zephyr-env.sh
	# On Windows
	set ZEPHYR_BASE=%cd%

	#. 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

	On Linux/macOS you can also build with ``make`` instead of ``ninja``:

	.. zephyr-app-commands::
	:zephyr-app: samples/hello_world
	:generator: make
	:host-os: unix
	: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

	ninja 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

	# On Linux/macOS
	unset ZEPHYR_GCC_VARIANT
	unset ZEPHYR_SDK_INSTALL_DIR
	cd <zephyr git clone location>
	source zephyr-env.sh
	# On Windows
	set ZEPHYR_GCC_VARIANT=
	set ZEPHYR_SDK_INSTALL_DIR=
	cd <zephyr git clone location>
	set ZEPHYR_BASE=%cd%


	#. On UNIX platforms, 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 `Using Custom and 3rd Party Cross Compilers`_ for
	details.

	.. _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 `Building
	without the Zephyr SDK`_ 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:`<user folder>/gcc-arm-none-eabi-5_3-2016q1/`.

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

	.. code-block:: console

	# On Linux/macOS
	export GCCARMEMB_TOOLCHAIN_PATH="~/gcc-arm-none-eabi-5_3-2016q1/"
	export ZEPHYR_GCC_VARIANT=gccarmemb
	# On Windows
	set GCCARMEMB_TOOLCHAIN_PATH="%userprofile%\gcc-arm-none-eabi-5_3-2016q1\"
	set 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:

	.. zephyr-app-commands::
	:zephyr-app: samples/hello_world
	:host-os: unix
	:board: qemu_x86
	:goals: build run

	To exit the qemu emulator, press ``Ctrl-a``, followed by ``x``.

	Use the ``qemu_cortex_m3`` board configuration to test the ARM build.

	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.

	Running a Sample Application natively (POSIX OS)
	================================================

	It is also possible to compile some of the sample and test applications to run
	as native process on a POSIX OS (e.g. Linux).
	To be able to do this, remember to have installed the 32 bit libC if your OS is
	natively 64bit.

	To compile and run an application in this way, type:

	.. zephyr-app-commands::
	:zephyr-app: samples/hello_world
	:host-os: unix
	:board: native_posix
	:goals: build

	and then:

	.. code-block:: console

	ninja run
	# or just:
	zephyr/zephyr.exe
	# Press Ctrl+C to exit

	This executable can be instrumented like any other Linux process. For ex. with gdb
	or valgrind.
	Note that the native port is currently only tested in Linux.

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