diff --git a/doc/getting_started/building_zephyr.rst b/doc/getting_started/building_zephyr.rst deleted file mode 100644 index 39bb1da7865..00000000000 --- a/doc/getting_started/building_zephyr.rst +++ /dev/null @@ -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 `. 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. diff --git a/doc/getting_started/developing.rst b/doc/getting_started/developing.rst deleted file mode 100644 index fc681e9ec00..00000000000 --- a/doc/getting_started/developing.rst +++ /dev/null @@ -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. \ No newline at end of file diff --git a/doc/getting_started/getting_started.rst b/doc/getting_started/getting_started.rst index 7e8f9e6f9b2..5c965f38915 100644 --- a/doc/getting_started/getting_started.rst +++ b/doc/getting_started/getting_started.rst @@ -3,19 +3,147 @@ 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: +Use this guide to get started with your Zephyr development. + +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:: :maxdepth: 1 - setting_up.rst - developing.rst - building_zephyr.rst + installation_linux.rst + installation_mac.rst + installation_win.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 is not impeded by a firewall. +Checking Out the Source Code Anonymously +======================================== + +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 `. 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/ diff --git a/doc/getting_started/installation_linux.rst b/doc/getting_started/installation_linux.rst index 197575fafce..bf4fbbbc5bb 100644 --- a/doc/getting_started/installation_linux.rst +++ b/doc/getting_started/installation_linux.rst @@ -46,10 +46,6 @@ Install the following with either apt-get or dnf. 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 @@ -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. 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 @@ -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 version: - .. code-block:: console + .. code-block:: console $ wget https://nexus.zephyrproject.org/content/repositories/releases/org/zephyrproject/zephyr-sdk/-i686/zephyr-sdk--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: - .. code-block:: console + .. code-block:: console - $ chmod +x zephyr-sdk--i686-setup.run + $ chmod +x zephyr-sdk--i686-setup.run - $ sudo ./zephyr-sdk--i686-setup.run + $ sudo ./zephyr-sdk--i686-setup.run - .. note:: - Replace with the version number of the SDK that you downloaded. - - .. note:: - There is no need for `sudo` if the SDK is installed in the current - user's home directory. + 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 + .. 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= To use the same toolchain in new sessions in the future you can set the variables in the file :file:`${HOME}/.zephyrrc`, for example: diff --git a/doc/getting_started/installation_mac.rst b/doc/getting_started/installation_mac.rst index 0d6e6815827..c3f3dbb0c2d 100644 --- a/doc/getting_started/installation_mac.rst +++ b/doc/getting_started/installation_mac.rst @@ -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 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: @@ -28,9 +35,7 @@ build for and install tools that the build system requires. 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. +Before proceeding with the build, ensure your OS is up to date. First, install the :program:`Homebrew` (The missing package manager for OS X). Homebrew is a free and open-source software package management system diff --git a/doc/getting_started/setting_up.rst b/doc/getting_started/setting_up.rst deleted file mode 100644 index 357b3176a28..00000000000 --- a/doc/getting_started/setting_up.rst +++ /dev/null @@ -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/