diff --git a/doc/application/apps_dev_process.rst b/doc/application/apps_dev_process.rst index aec598ab52c..e7fa7226752 100644 --- a/doc/application/apps_dev_process.rst +++ b/doc/application/apps_dev_process.rst @@ -10,7 +10,7 @@ Before you build ---------------- * Check that your Linux host meets the minimum requirements specified in the - :ref:`quick_start`. + :ref:`getting_started`. * Check that environment variables have been configured correctly as outlined in :ref:`apps_common_procedures`. diff --git a/doc/collaboration/code/gerrit.rst b/doc/collaboration/code/gerrit.rst index b5b2c172e44..8180470efad 100644 --- a/doc/collaboration/code/gerrit.rst +++ b/doc/collaboration/code/gerrit.rst @@ -25,8 +25,8 @@ Make sure to subscribe to the `mailing list`_ by filling out the .. _mailing list: foss-rtos-collab@lists.01.org -Follow the steps available at :ref:`access_source` for information about how to access the source -code using Git and Gerrit. +Follow the steps available at :ref:`code_check_out` for information about how +to access the source code using Git and Gerrit. Gerrit is a review system, and as such, assigns the following roles to users: @@ -55,7 +55,7 @@ Currently, Gerrit is only one method to submit a change for review. Before submitting, please ensure each commit conforms with coding and contribution guidelines. Directions for building the source code -are beyond the scope of this document. Please see the :ref:`quick_start` +are beyond the scope of this document. Please see the :ref:`getting_started` for further detail. When a change is ready for submission, Gerrit requires that the diff --git a/doc/collaboration/documentation/cross.rst b/doc/collaboration/documentation/cross.rst index 35e627ef240..32c36bc5ae3 100644 --- a/doc/collaboration/documentation/cross.rst +++ b/doc/collaboration/documentation/cross.rst @@ -31,7 +31,7 @@ These are some examples of proper labels: .. code-block:: rst - .. _quick_start: + .. _getting_started: .. _gerrit_access: diff --git a/doc/getting_started/building_zephyr.rst b/doc/getting_started/building_zephyr.rst new file mode 100644 index 00000000000..1a31c1259df --- /dev/null +++ b/doc/getting_started/building_zephyr.rst @@ -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 `. 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. diff --git a/doc/getting_started/developing.rst b/doc/getting_started/developing.rst new file mode 100644 index 00000000000..d187733388c --- /dev/null +++ b/doc/getting_started/developing.rst @@ -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. \ No newline at end of file diff --git a/doc/getting_started/getting_started.rst b/doc/getting_started/getting_started.rst new file mode 100644 index 00000000000..51aa677dd2f --- /dev/null +++ b/doc/getting_started/getting_started.rst @@ -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. diff --git a/doc/getting_started/installation_linux.rst b/doc/getting_started/installation_linux.rst new file mode 100644 index 00000000000..d24cdf809b7 --- /dev/null +++ b/doc/getting_started/installation_linux.rst @@ -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/ \ No newline at end of file diff --git a/doc/quick_start/installation_mac.rst b/doc/getting_started/installation_mac.rst similarity index 70% rename from doc/quick_start/installation_mac.rst rename to doc/getting_started/installation_mac.rst index f13306a697d..f7b2f077505 100644 --- a/doc/quick_start/installation_mac.rst +++ b/doc/getting_started/installation_mac.rst @@ -3,12 +3,12 @@ Development Environment Setup on Mac OS ####################################### -This section describes how to build the kernel in a development system. +This section describes how to set up a Mac OS development system. -This guide was tested by compiling and running the Zephyr Kernel's sample +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 **************************** @@ -24,19 +24,27 @@ 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 site ``_ and follow the +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 successfuly installed, install the following tools using the -brew command line. +After Homebrew was successfully installed, install the following tools using +the brew command line. .. code-block:: console @@ -51,7 +59,7 @@ brew command line. $ brew install crosstool-ng Alternatively you can install the latest version of :program:`crosstool-ng` -from source. Download the latest version from http://crosstool-ng.org. The +from source. Download the latest version from the `crosstool-ng site`_. The latest version usually supports the latest released compilers. .. code-block:: console @@ -69,10 +77,17 @@ latest version usually supports the latest released compilers. $ 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-senstive file system (OS X Extended (Case-sensitive, Journaled) and +case-sensitive file system (OS X Extended (Case-sensitive, Journaled) and mount it. Alternatively you can use the script below to create the image: @@ -84,7 +99,6 @@ Alternatively you can use the script below to create the image: && 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: @@ -96,6 +110,9 @@ When mounted, the file system of the image will be available under $ 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. @@ -112,17 +129,16 @@ yourself using the configuration menus: $ ct-ng menuconfig -To build a kernel image for your desired architecture and platform, perform -these steps: +Verifying the Configuration of the Toolchain +============================================ -1. Select the architecture for which you are building the kernel. -2. Select the target platform on which that kernel will run. -3. Save the configuration. -4. Build the toolchain with the saved configuration. -5. Ensure that the build and installation directories are set correctly. -6. Open the generated :file:`.config` file and verify the following (assuming - the sparse image was mounted under :file:`/Volumes/CrossToolNG`): +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 @@ -134,9 +150,13 @@ these steps: CT_INSTALL_DIR="${CT_PREFIX_DIR}" ... -Now you are ready to build the toolchain: +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 @@ -153,3 +173,7 @@ and use the target location where the toolchain was installed, type: $ export ZEPHYR_SDK_INSTALL_DIR=/Volumes/CrossToolNG/x-tools + +.. _Homebrew site: http://brew.sh/ + +.. _crosstool-ng site: http://crosstool-ng.org diff --git a/doc/getting_started/setting_up.rst b/doc/getting_started/setting_up.rst new file mode 100644 index 00000000000..9e581c83f45 --- /dev/null +++ b/doc/getting_started/setting_up.rst @@ -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 \ No newline at end of file diff --git a/doc/index.rst b/doc/index.rst index 0e47d250a7c..94d2234d0bd 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -8,7 +8,7 @@ Getting Started :maxdepth: 1 about_zephyr.rst - quick_start/quick_start.rst + getting_started/getting_started.rst kernel/kernel.rst diff --git a/doc/quick_start/application.rst b/doc/quick_start/application.rst deleted file mode 100644 index ca61f31801c..00000000000 --- a/doc/quick_start/application.rst +++ /dev/null @@ -1,83 +0,0 @@ -.. _building_zephyr: - -Building and Running a Sample Application -######################################### - - -Building a Sample Application from Source -========================================= - -To build an example application follow these steps: - -#. Go to the root directory of the Zephyr Project. - -#. Set the paths properly in the :file:`$ZEPHYR_BASE` directory, - type: - - .. code-block:: console - - $ source zephyr-env.sh - -#. Build the example project, type: - - .. 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 Makefile, for example: - -.. code-block:: console - - $ make BOARD=minnowboard - -You can build for a different platform by defining the variable BOARD -with one of the supported platforms. -For a list of supported platforms of a particular architecture, run: - -.. code-block:: console - - $ make ARCH= 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 default ELF binaries generated by the build system are named zephyr.elf. The -build system generates different format for different use cases and 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. - -To 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 platforms and architectures and 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/quick_start/installation_linux.rst b/doc/quick_start/installation_linux.rst deleted file mode 100644 index 5b29b0ded15..00000000000 --- a/doc/quick_start/installation_linux.rst +++ /dev/null @@ -1,71 +0,0 @@ -.. _installing_zephyr_linux: - -Development Environment Setup on Linux -###################################### - -This section describes how to build the kernel in a development system. - -This guide was tested by compiling and running the Zephyr Kernel's sample -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. - -.. _linux_development_system: - -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. - -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. - -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 - -.. _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. - -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 diff --git a/doc/quick_start/local_development.rst b/doc/quick_start/local_development.rst deleted file mode 100644 index c123709a3c2..00000000000 --- a/doc/quick_start/local_development.rst +++ /dev/null @@ -1,196 +0,0 @@ -.. _setup_development_environment: - -Setup a Local Development Environment -##################################### - -.. _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 host system. - -#. Download the SDK self-extractable binary from: - - https://zephyr-download.01.org/zephyr-sdk/zephyr-sdk-0.7.1-i686-setup.run - - .. code-block:: console - - $ wget --user=USERNAME --ask-password \ - https://zephyr-download.01.org/zephyr-sdk/zephyr-sdk-0.7.1-i686-setup.run - -#. Run the installation binary, type: - - .. code-block:: console - - $ chmod +x zephyr-sdk-0.7.1-i686-setup.run - - $ sudo ./zephyr-sdk-0.7.1-i686-setup.run - - -#. 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/ - - - - -The Zephyr Project's source code is maintained using Git and is served using -Gerrit. - -Gerrit access requires some basic user setup. The following process shows -a simple walk-through to enable quick access to the Gerrit services. - -.. _access_source: - -Getting Access -============== - -#. `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 SSH to Use Gerrit -============================= - -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. - -#. Create a key-pair in your Linux machine, type: - - .. 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 ~/.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 - - -#. Add your public key :file:`id_rsa.pub` to the Gerrit account: - - a) Go to `access Gerrit`_. - - b) Click on your account name in the upper right corner. - - c) From the pop-up menu, select :guilabel:`Settings`. - - d) On the left side menu, click on :guilabel:`SSH Public Keys`. - - e) Click Add key and paste the contents of your public key :file:`~/.id/id_rsa.pub`. - -.. note:: To obtain the contents of your public key on a Linux machine: - - :command:`$ cat ~/.ssh/id_rsa.pub` - - The output is the contents of :file:`~/.id/id_rsa.pub`. Paste it into the - '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`. - -.. _checking_source_out: - -Checking Out the Source Code -============================ - - -#. Ensure that SSH has been set up properly. See `Configuring SSH to Use Gerrit`_ - 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. - -#. Change to the main project directory: - - .. code-block:: console - - $ cd zephyr-project - -#. Source the project environment file to setup project variables: - - .. code-block:: console - - $ source zephyr-env.sh diff --git a/doc/quick_start/quick_start.rst b/doc/quick_start/quick_start.rst deleted file mode 100644 index 352ebb7ea2f..00000000000 --- a/doc/quick_start/quick_start.rst +++ /dev/null @@ -1,29 +0,0 @@ -.. _quick_start: - -Quick Start Guide -################# - -Use this guide to install the Zephyr development environment on your -development system and to build the Zephyr Kernel on the supported platforms. - -The following operating systems are supported: - -* Linux -* Mac OS - -Follow the steps appropriate for your development system's -:abbr:`OS (Operating System)`. - -Use these procedures to create a new development environment. Given that the -file hierarchy may change from one release to another, these instructions -might not work properly in an existing development environment. - -Perform the steps in the installation procedures in the order they appear. - -.. toctree:: - :maxdepth: 2 - - installation_linux.rst - installation_mac.rst - local_development.rst - application.rst