diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 52eff45c92c..3dbc63382d3 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -144,7 +144,7 @@ and how to set up your development environment as introduced in the Zephyr https://www.zephyrproject.org/doc/getting_started/getting_started.html The examples below use a Linux host environment for Zephyr development. -You should be familiar with common developer tools such as Git and Make, and +You should be familiar with common developer tools such as Git and CMake, and platforms such as GitHub. If you haven't already done so, you'll need to create a (free) GitHub account @@ -233,18 +233,15 @@ run the same tests the CI system runs, follow these steps from within your local Zephyr source working directory:: $ source zephyr-env.sh - $ make host-tools - $ export PREBUILT_HOST_TOOLS=${ZEPHYR_BASE}/bin - $ export USE_CCACHE=1 - $ ./scripts/sanitycheck + $ ./scripts/sanitycheck --ccache The above will execute the basic sanitycheck script, which will run various kernel tests using the QEMU emulator. It will also do some build tests on various samples with advanced features that can't run in QEMU. -We highly recommend you run these tests locally to avoid any CI failures. -Using CCACHE and pre-built host tools is optional, however it speeds up the -execution time considerably. +We highly recommend you run these tests locally to avoid any CI +failures. Enabling ccache with --ccache is optional, but it will speed +up the execution time considerably. Coding Style diff --git a/doc/README.rst b/doc/README.rst index bb6d4390b5e..d027b3b5e0e 100644 --- a/doc/README.rst +++ b/doc/README.rst @@ -100,6 +100,7 @@ commands to generate the html content locally: $ cd ~/zephyr $ source zephyr-env.sh + $ cd doc $ make htmldocs Depending on your development system, it will take about 15 minutes to diff --git a/doc/application/application.rst b/doc/application/application.rst index 1abf331a836..b58f2801e71 100644 --- a/doc/application/application.rst +++ b/doc/application/application.rst @@ -32,14 +32,24 @@ An application in the simplest form has the following structure: configuration option values are used; if no existing values are provided, the kernel's default configuration values are used. -* **Makefile**: This file tells the build system where to find the files +* **CMakeLists.txt**: This file tells the build system where to find the files mentioned above, as well as the desired target board configuration. -Once the application has been defined, it can be built with a single ``make`` -call. -The results of the build process are located in a sub-directory called -:file:`outdir/BOARD`. This directory contains the files generated by the build -process, the most notable of which are listed below. +Once the application has been defined, project files for building it +can be generated by calling cmake. The project files will be written +to the directory where cmake was called, this directory is known as +the build directory. + +The most notable files in the build directory are listed below. + +* The :file:`Makefile` (or :file:`build.ninja`) project file that can + be invoked to build the application. + +* The :file:`zephyr` directory is the working directory of the + generated build system and where most generated files are located. + +After the underlying build tool has been invoked the build output will +be written to the :file:`zephyr` directory. * The :file:`.config` file that contains the configuration settings used to build the application. @@ -51,14 +61,13 @@ process, the most notable of which are listed below. kernel binary. - Application Structure ********************* Create one directory for your application and a sub-directory for the -application's source code; this makes it easier to organize directories and -files in the structure that the kernel expects. +application's source code; this makes it easier to distinguish between +project files and source code. #. Create an application directory structure outside of the kernel's installation directory tree. Often this is your workspace directory. @@ -95,28 +104,22 @@ files in the structure that the kernel expects. Application Definition ********************** -An application is integrated into the build system by including the Makefile.inc -file provided. +An application is integrated into the build system with two lines of +boilerplate code in it's :file:`CMakeLists.txt` file and by having the +environment variable :makevar:`ZEPHYR_BASE` set. -.. code-block:: make +.. code-block:: cmake - include $(ZEPHYR_BASE)/Makefile.inc + include($ENV{ZEPHYR_BASE}/cmake/app/boilerplate.cmake NO_POLICY_SCOPE) + project(NONE) The following predefined variables configure the development project: -* :makevar:`ZEPHYR_BASE`: Sets the path to the kernel's base directory. - This variable is usually set by the :file:`zephyr_env.sh` script. - It can be used to get the kernel's base directory, as used in the - Makefile.inc inclusion above, or it can be overridden to select an - specific instance of the kernel. - -* :makevar:`PROJECT_BASE`: Provides the developer's application project - directory path. It is set by the :file:`Makefile.inc` file. - -* :makevar:`SOURCE_DIR`: Overrides the default value for the application's - source code directory. The developer source code directory is set to - :file:`$(PROJECT_BASE)/src/` by default. This directory name should end - with slash **'/'**. +* :makevar:`ZEPHYR_BASE`: Sets the path to the kernel's base + directory. This variable is usually set by the + :file:`zephyr_env.sh` script. It can be used to get the kernel's + base directory, as used in the boilerplate above, or it can be + overridden to select an specific instance of the kernel. * :makevar:`BOARD`: Selects the board that the application's build will use for the default configuration. @@ -125,155 +128,96 @@ The following predefined variables configure the development project: This file includes the kconfig configuration values that override the default configuration values. -* :makevar:`O`: Optional. Indicates the output directory that Kconfig uses. - The output directory stores all the files generated during the build - process. The default output directory is the :file:`$(PROJECT_BASE)/outdir` - directory. - - -Makefiles +CMake ********* Overview ======== -The build system defines a set of conventions for the correct use of Makefiles -in the kernel source directories. The correct use of Makefiles is driven by the -concept of recursion. +CMake is used to build Zephyr. A CMake build is done in two +stages. The first stage is called Configuration, during Configuration +the CMakeLists.txt build scripts are executed. At the end of +Configuration, CMake will have an internal model of the Zephyr build +and can generate build scripts that are native to the host platform. -In the recursion model, each Makefile within a directory includes the source -code and any subdirectories to the build process. Each subdirectory follows -the same principle. Developers can focus exclusively in their own work. They -integrate their module with the build system by adding a very simple Makefile -following the recursive model. +CMake supports generating several build systems, but only Ninja and +Make are tested and supported by Zephyr. After Configuration and +Generation the user can begin the Build stage by executing the +generated build system. The build system will for most code changes be +able to re-build the application without involving CMake. But for +certain configuration changes the Configuration step will need to be +executed again, either automatically by the build system, or even +manually in some cases. -.. _makefile_conventions: +Zephyr uses CMake's concept of a 'target' to organize the build. A +target can be an executable, a library, or a generated file. For +application developers, the library target is the most important to +understand. All source code that goes into a Zephyr build does so by +being included in a library target, even application code. -Makefile Conventions -==================== +Library targets have source code, that is added through CMakeLists.txt +build scripts like this: -The following conventions restrict how to add modules and Makefiles to the -build system. These conventions ensure the correct implementation of the -recursive model. +.. code-block:: cmake -* Each source code directory must contain a single Makefile. Directories - without a Makefile are not considered source code directories. + target_sources(app PRIVATE src/main.c) -* The scope of every Makefile is restricted to the contents of that directory. - A Makefile can only make a direct reference to files and subdirectories on the - same level or below. +In the above code an existing library target named 'app' is being +configured to have the source file src/main.c. The PRIVATE keyword +indicates that we are modifying the internals of how the library is +being built. Whereas using the keyword 'PUBLIC' would modify how other +libraries that link with app are built. In this case, using PUBLIC +here would cause libraries that link with app to also include the +source file src/main.c, behaviour that we surely do not want. The +'PUBLIC' keyword could however be useful when modifying the include +paths of a target library. -* Makefiles list the object files that are included in the link process. The - build system finds the source file that generates the object file by matching - the object file name to the source file. +Application CMakeLists.txt +************************** -* Parent directories add their child directories into the recursion model. +Every application must have a CMakeLists.txt file. The application +CMakeLists.txt file is the entry point, or toplevel of the build +system that builds the :file:`zephyr.elf` image. :file:`zephyr.elf` +contains both the application and the kernel libraries. -* The root Makefile adds the directories in the kernel base directory into the - recursion model. +#. Open the :file:`CMakeLists.txt` and add the following mandatory + entries using any text editor. -Adding Source Files -=================== - -The Makefile must refer the source build indirectly, specifying the object file -that results from the source file using the :literal:`obj-y` variable. For -example, if the file that we want to add is a C file named :file:`.c` the -following line should be added in the Makefile: - -.. code-block:: make - - obj-y += .o - -.. note:: - - The same method applies for assembly files with the .S extension. - -Source files can be added conditionally using configuration options. For -example, if the option ``CONFIG_VAR`` is set and it implies that a source -file must be added in the compilation process, then the following line adds the -source code conditionally: - -.. code-block:: none - - obj-$(CONFIG_VAR) += .o - -Adding Directories -================== - -Add a subdirectory to the build system by editing the Makefile in its -directory. The subdirectory is added using the :literal:`obj-y` variable. The -correct syntax to add a subdirectory into the build queue is: - -.. code-block:: make - - obj-y += / - -The backslash at the end of the directory name signals the build system that a -directory, and not a file, is being added to the build queue. - -The conventions require us to add only one directory per line and never to mix -source code with directory recursion in a single :literal:`obj-y` line. This -helps keep the readability of the Makefile by making it clear when an item adds -an additional lever of recursion. - -Directories can also be conditionally added: - -.. code-block:: none - - obj-$(CONFIG_VAR) += / - -The subdirectory must contain its own Makefile following the rules described in -:ref:`makefile_conventions`. - - -Application Makefile -******************** - -Create an application Makefile to define basic information, such as the board -configuration used by the application. The build system uses the Makefile to -build a :file:`zephyr.elf` image that contains both the application and the -kernel libraries. - -#. Open the :file:`Makefile` and add the following mandatory - entries using any standard text editor. - - .. note:: - - Ensure that there is a space before and after each ``=``. - -#. Add the name of the default board configuration for your application on a +#. Add the name of the board configuration for your application on a new line: - .. code-block:: make + .. code-block:: cmake - BOARD = board_configuration_name + set(BOARD qemu_x86) The supported boards can be found in :ref:`boards`. -#. Add the name of the default kernel configuration file for your - application on a new line: +#. Include the mandatory boilerplate that integrates the application + with the Zephyr build system on a new line: - .. code-block:: make + .. code-block:: cmake - CONF_FILE ?= kernel_configuration_name + include($ENV{ZEPHYR_BASE}/cmake/app/boilerplate.cmake NO_POLICY_SCOPE) + project(NONE) -#. Include the mandatory :file:`Makefile` on a new line: +#. Add any application source files to the 'app' target library: - .. code-block:: make + .. code-block:: cmake - include ${ZEPHYR_BASE}/Makefile.inc + target_sources(app PRIVATE src/main.c) -#. Save and close the :file:`Makefile`. +#. Save and close the :file:`CMakeLists.txt`. +Below is an example CMakeList.txt: -Below is an example Makefile: +.. code-block:: cmake -.. code-block:: make + set(BOARD qemu_x86) - BOARD = qemu_x86 - CONF_FILE = prj.conf + include($ENV{ZEPHYR_BASE}/cmake/app/boilerplate.cmake NO_POLICY_SCOPE) + project(NONE) - include ${ZEPHYR_BASE}/Makefile.inc + target_sources(app PRIVATE src/main.c) .. _application_configuration: @@ -289,10 +233,10 @@ The available sources are (in order): #. The application's current configuration. (i.e. The :file:`.config` file.) -#. The application's default configuration. (i.e. The :file:`.conf` file.) +#. The application's default configuration. (Specified by ``CONF_FILE``, i.e. :file:`prj.conf`.) #. The board configuration used by the application. - (i.e. The board's :file:`.defconfig` file.) + (i.e. The board's :file:`_defconfig` file.) #. The kernel's default configuration. (i.e. One of the kernel's :file:`Kconfig` files.) @@ -322,8 +266,10 @@ in :file:`$ZEPHYR_BASE/boards/ARCHITECTURE/BOARD/BOARD_defconfig`. $ vim prj.conf - The default name is :file:`prj.conf`. The filename must match the - ``CONF_FILE`` entry in the application :file:`Makefile`. + The application's default configuration is specified by + ``CONF_FILE``, ``CONF_FILE`` defaults to :file:`prj.conf` unless + configured otherwise in the application :file:`CMakeLists.txt` + file. #. Edit the file and add the appropriate configuration entries. @@ -363,7 +309,7 @@ Configure the kernel options using a menu-driven interface. While you can add entries manually, using the configuration menu is a preferred method. -#. Run the :command:`make menuconfig` rule to launch the menu-driven interface. +#. After generating project files run :command:`ninja menuconfig` to launch the menu-driven interface. a) In a terminal session, navigate to the application directory (:file:`~/app`). @@ -372,7 +318,8 @@ entries manually, using the configuration menu is a preferred method. .. code-block:: bash - $ make [BOARD=] menuconfig + $ cmake -Bbuild -H. -GNinja + $ ninja -C build menuconfig A question-based menu opens that allows you to set individual configuration options. @@ -427,9 +374,8 @@ entries manually, using the configuration menu is a preferred method. Typically, you will save to the default file name unless you are experimenting with various configuration scenarios. - An :file:`outdir` directory is created in the application directory. The - outdir directory contains symbolic links to files under - :file:`\$ZEPHYR_BASE`. + A :file:`zephyr` directory will have been created in the build + directory. .. note:: @@ -439,7 +385,7 @@ entries manually, using the configuration menu is a preferred method. :file:`.config`, rename it to something other than :file:`.config`. Kernel configuration files, such as the :file:`.config` file, are saved - as hidden files in :file:`outdir`. To list all your kernel configuration + as hidden files in :file:`zephyr`. To list all your kernel configuration files, enter :command:`ls -a` at the terminal prompt. The following dialog opens, displaying the file name the configuration @@ -488,16 +434,10 @@ entries manually, using the configuration menu is a preferred method. Application-Specific Code ************************* -Application-specific source code files are normally added to the application's -:file:`src` directory. If the application adds a large number of files the -developer can group them into sub-directories under :file:`src`, to whatever -depth is needed. The developer must supply a :file:`Makefile` for the -:file:`src` directory, as well as for each sub-directory under :file:`src`. - -.. note:: - - These Makefiles are distinct from the top-level application Makefile - that appears in :file:`~/app`. +Application-specific source code files are normally added to the +application's :file:`src` directory. If the application adds a large +number of files the developer can group them into sub-directories +under :file:`src`, to whatever depth is needed. Application-specific source code should not use symbol name prefixes that have been reserved by the kernel for its own use. For more information, see @@ -505,58 +445,6 @@ been reserved by the kernel for its own use. For more information, see `Naming Conventions `_. - -The following requirements apply to all Makefiles in the :file:`src` -directory, including any sub-directories it may have. - -* During the build process, Kbuild identifies the source files to compile - into object files by matching the file names identified in - the application's Makefile(s). - - .. important:: - - A source file that is not referenced by any Makefile is not included - when the application is built. - -* A Makefile cannot directly reference source code. It can only - reference object files (:file:`.o` files) produced from source code files. - -* A Makefile can only reference files in its own directory or in the - sub-directories of that directory. - -* A Makefile may reference multiple files from a single-line entry. - However, a separate line must be used to reference each directory. - - - -#. Create a directory structure for your source code in :file:`src` - and add your source code files to it. - -#. Create a :file:`Makefile` in the :file:`src` directory. Then create - an additional :file:`Makefile` in each of the sub-directories under - the :file:`src` directory, if any. - - a) Use the following syntax to add file references: - - .. code-block:: make - - obj-y += file1.o file2.o - - b) Use the following syntax to add directory references: - - .. code-block:: make - - obj-y += directory_name/** - - -This example is taken from the :ref:`dining-philosophers-sample`. To examine this file in -context, navigate to: :file:`$ZEPHYR_BASE/samples/philosophers/src`. - -.. code-block:: make - - obj-y = main.o - - Support for building third-party library code ============================================= @@ -567,31 +455,22 @@ compiler flags that control the ABI targeted, making it important that both libraries and applications have certain compiler flags in common. It may also be useful for glue code to have access to Zephyr kernel header files. -To make it easier to integrate third-party components, the Zephyr build system -includes a special build target, ``outputexports``, that takes a number of -critical variables from the Zephyr build system and copies them into -:file:`Makefile.export`. This allows the critical variables to be included by -wrapper code for use in a third-party build system. +To make it easier to integrate third-party components, the Zephyr +build system has defined CMake functions that give application build +scripts access to the zephyr compiler options. The functions are +documented and defined in :file:`$ZEPHYR_BASE/cmake/extensions.cmake` +and follow the naming convention ``zephyr_get__``. -The following variables are recommended for use within the third-party build -(see :file:`Makefile.export` for the complete list of exported variables): +The following variables will often need to be exported to the +third-party build system. -* ``CROSS_COMPILE``, together with related convenience variables to call the - cross-tools directly (including ``AR``, ``AS``, ``CC``, ``CXX``, ``CPP`` - and ``LD``). +* ``CMAKE_C_COMPILER``, ``CMAKE_AR``. * ``ARCH`` and ``BOARD``, together with several variables that identify the Zephyr kernel version. -* ``KBUILD_CFLAGS``, ``NOSTDINC_FLAGS`` and ``ZEPHYRINCLUDE`` all of which - should normally be added, in that order, to ``CFLAGS`` (or - ``CXXFLAGS``). - -* All kconfig variables, allowing features of the library code to be - enabled/disabled automatically based on the Zephyr kernel configuration. - -:file:`samples/application_development/static_lib` is a sample project that demonstrates -some of these features. +:file:`samples/application_development/external_lib` is a sample +project that demonstrates some of these features. .. _build_an_application: @@ -605,13 +484,16 @@ hardware. #. Navigate to the application directory :file:`~/app`. -#. Enter the following command to build the application's :file:`zephyr.elf` - image using the configuration settings for the board type specified - in the application's :file:`Makefile`. +#. Enter the following commands to build the application's + :file:`zephyr.elf` image using the configuration settings for the + board type specified in the application's :file:`CMakeLists.txt`. .. code-block:: console - $ make + $ mkdir build + $ cd build + $ cmake -GNinja .. + $ ninja If desired, you can build the application using the configuration settings specified in an alternate :file:`.conf` file using the :code:`CONF_FILE` @@ -620,15 +502,14 @@ hardware. .. code-block:: console - $ make CONF_FILE=prj.alternate.conf - If desired, you can build the application for a different board type than the - one specified in the application's :file:`Makefile` using the :code:`BOARD` - parameter. For example: + $ export CONF_FILE=prj.alternate.conf + $ cmake -GNinja .. - .. code-block:: console - - $ make BOARD=arduino_101 + If desired, you can generate project files for a different board + type than the one specified in the application's + :file:`CMakeLists.txt` by defining the environment variable + :code:`BOARD`. Both the :code:`CONF_FILE` and :code:`BOARD` parameters can be specified when building the application. @@ -640,7 +521,7 @@ Application development is usually fastest when changes are continually tested. Frequently rebuilding your application makes debugging less painful as the application becomes more complex. It's usually a good idea to rebuild and test after any major changes to the application's source files, -Makefiles, or configuration settings. +CMakeLists.txt files, or configuration settings. .. important:: @@ -654,23 +535,24 @@ the build system to rebuild the entire application from scratch with the following procedure: -#. Navigate to the application directory :file:`~/app`. +#. Navigate to the build directory :file:`~/app/build`. -#. Enter the following command to delete the application's generated files - for the specified board type, except for the :file:`.config` file that - contains the application's current configuration information. +#. Enter the following command to delete the application's generated + files, except for the :file:`.config` file that contains the + application's current configuration information. .. code-block:: console - $ make [BOARD=] clean + $ ninja clean - Alternatively, enter the following command to delete *all* generated files - for *all* board types, including the :file:`.config` files that contain - the application's current configuration information for those board types. + Alternatively, enter the following command to delete *all* + generated files, including the :file:`.config` files that contain + the application's current configuration information for those board + types. .. code-block:: console - $ make pristine + $ ninja pristine #. Rebuild the application normally following the steps specified in `Build an Application`_ above. @@ -721,13 +603,13 @@ run an application via QEMU: #. Open a terminal console on your host computer, and navigate to the application directory :file:`~/app`. -#. Enter the following command to build and run the application - using a QEMU-supported board configuration, such as qemu_cortex_m3 or - qemu_x86. +#. After generating project files for a QEMU-supported board + configuration, such as qemu_cortex_m3 or qemu_x86, enter the + following command to build and run the application. .. code-block:: console - $ make [BOARD= ...] run + $ ninja run The Zephyr build system generates a :file:`zephyr.elf` image file and then begins running it in the terminal console. @@ -758,7 +640,7 @@ The simplest way to debug an application running in QEMU is using the GNU Debugger and setting a local GDB server in your development system through QEMU. You will need an ELF binary image for debugging purposes. The build system -generates the image in the output directory. By default, the kernel binary name +generates the image in the build directory. By default, the kernel binary name is :file:`zephyr.elf`. The name can be changed using a Kconfig option. We will use the standard 1234 TCP port to open a :abbr:`GDB (GNU Debugger)` @@ -782,11 +664,11 @@ The options used above have the following meaning: TCP port 1234. To debug with QEMU and to start a GDB server and wait for a remote connect, run -the following inside an application: +the following inside the build directory of an application: .. code-block:: bash - make BOARD=qemu_x86 debugserver + ninja debugserver The build system will start a QEMU instance with the CPU halted at startup and with a GDB server instance listening at the TCP port 1234. diff --git a/doc/getting_started/getting_started.rst b/doc/getting_started/getting_started.rst index 0d15a2c33af..b956ffb0ecb 100644 --- a/doc/getting_started/getting_started.rst +++ b/doc/getting_started/getting_started.rst @@ -70,7 +70,7 @@ To build an example application follow these steps: .. code-block:: console - $ cd zephyr-project + $ cd zephyr #. Source the project environment file to set the project environment variables: @@ -79,21 +79,36 @@ To build an example application follow these steps: $ source zephyr-env.sh -#. Build the :ref:`hello_world` example project, enter: +#. Generate project files for the :ref:`hello_world` example, enter: .. code-block:: console $ cd $ZEPHYR_BASE/samples/hello_world - $ make + $ mkdir build + $ cd build + $ cmake -GNinja .. -The above invocation of make will build the :ref:`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: +The above will generate project files that can build the +:ref:`hello_world` sample application using the default settings +defined in the application's CMakeLists.txt. To build the application, +enter: .. code-block:: console - $ make BOARD=arduino_101 + $ cd $ZEPHYR_BASE/samples/hello_world/build + $ ninja + +You can build for a different board by defining the variable BOARD +with one of the supported boards, for example: + +.. code-block:: console + + $ cd $ZEPHYR_BASE/samples/hello_world + $ export BOARD=arduino_101 + $ mkdir build_101 + $ cd build_101 + $ cmake -GNinja .. + $ ninja For further information on the supported boards go see :ref:`here `. Alternatively, run the following command to obtain a list @@ -101,13 +116,12 @@ of the supported boards: .. code-block:: console - $ make help + $ 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 -:file:`outdir` sub-directory under the application root directory, in a -subdirectory that matches the BOARD string. +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 @@ -133,12 +147,23 @@ follow the steps below to build with any custom or 3rd party cross-compilers: $ unset ZEPHYR_GCC_VARIANT $ unset ZEPHYR_SDK_INSTALL_DIR +#. Build Kconfig and add it to path + + .. code-block:: console + + $ mkdir ~/kconfig_build_dir && cd ~/kconfig_build_dir + $ cmake -GNinja $ZEPHYR_BASE/scripts + $ ninja + $ echo "export PATH=$PWD/kconfig:\$PATH" >> $HOME/.bashrc + $ bash + $ which conf + #. 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/`. -#. Navigate to the main project directory: +#. Navigate to the main project directory (where you cloned the Zephyr source from GitHub): .. code-block:: console @@ -151,29 +176,13 @@ follow the steps below to build with any custom or 3rd party cross-compilers: $ source zephyr-env.sh -#. Build the example :ref:`hello_world` project and make sure you supply the - CROSS_COMPILE on the command line, enter: +#. 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 - $ cd $ZEPHYR_BASE/samples/hello_world - $ make CROSS_COMPILE=~/gcc-arm-none-eabi-5_3-2016q1/bin/arm-none-eabi- BOARD=arduino_due - -The above will build the sample using the toolchain downloaded from -`GCC ARM Embedded`_. - -Alternatively, you can use the existing support for GCC ARM Embedded: - - .. code-block:: console - - $ export GCCARMEMB_TOOLCHAIN_PATH="~/gcc-arm-none-eabi-5_3-2016q1/" - $ export ZEPHYR_GCC_VARIANT=gccarmemb - $ cd zephyr-project - $ source zephyr-env.sh - $ cd $ZEPHYR_BASE/samples/hello_world - $ make BOARD=arduino_due + $ cmake -DBOARD=arduino_due -H$ZEPHYR_BASE/samples/hello_world -Bbld -GNinja && cmake --build bld Running a Sample Application in QEMU ==================================== @@ -189,13 +198,15 @@ type: .. code-block:: console - $ make BOARD=qemu_x86 run + $ cd $ZEPHYR_BASE/samples/hello_world + $ export BOARD=qemu_x86 + $ mkdir qemu_build + $ cd qemu_build + $ cmake -GNinja .. + $ ninja run -To run an application using the ARM qemu_cortex_m3 board configuration, type: - -.. code-block:: console - - $ make BOARD=qemu_cortex_m3 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 diff --git a/doc/getting_started/installation_linux.rst b/doc/getting_started/installation_linux.rst index b565afb6ef5..3ab6e806e68 100644 --- a/doc/getting_started/installation_linux.rst +++ b/doc/getting_started/installation_linux.rst @@ -52,16 +52,16 @@ Install the required packages in a Ubuntu host system with: .. code-block:: console - $ sudo apt-get install git make gcc g++ ncurses-dev gperf ccache\ - doxygen dfu-util device-tree-compiler python3-ply python3-pip + $ sudo apt-get install --no-install-recommends git ninja-build gperf \ + ccache doxygen dfu-util device-tree-compiler \ + python3-ply python3-pip python3-setuptools xz-utils file 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 glibc-static gperf ccache\ - libstdc++-static ncurses-devel \ + $ sudo dnf install git ninja-build gperf ccache\ doxygen dfu-util dtc python3-pip \ python3-ply python3-yaml dfu-util dtc python3-pykwalify @@ -69,6 +69,15 @@ Install additional packages required for development with Zephyr:: $ pip3 install --user -r scripts/requirements.txt +Install exactly version 3.8.2 of CMake:: + + $ mkdir $HOME/work_dir && cd $HOME/work_dir + $ wget https://cmake.org/files/v3.8/cmake-3.8.2-Linux-x86_64.sh + $ yes | sh cmake-3.8.2-Linux-x86_64.sh | cat + $ echo "export PATH=$PWD/cmake-3.8.2-Linux-x86_64/bin:\$PATH" >> $HOME/.bashrc + $ bash + $ cmake --version + .. _zephyr_sdk: Installing the Zephyr Software Development Kit @@ -118,8 +127,7 @@ Follow these steps to install the SDK on your Linux host system. .. code-block:: console - $ chmod +x zephyr-sdk--setup.run - $ ./zephyr-sdk--setup.run + $ sh zephyr-sdk--setup.run There is no need to use ``sudo`` if the SDK is installed in the current user's home directory. diff --git a/doc/introduction/introducing_zephyr.rst b/doc/introduction/introducing_zephyr.rst index 4ce26d762a5..6f6448be4a0 100644 --- a/doc/introduction/introducing_zephyr.rst +++ b/doc/introduction/introducing_zephyr.rst @@ -8,7 +8,7 @@ resource-constrained systems: from simple embedded environmental sensors and LED wearables to sophisticated smart watches and IoT wireless gateways. The Zephyr kernel supports multiple architectures, including ARM Cortex-M, Intel -x86, ARC, NIOS II, Tensilica Xtensa and RISC V. The full list of supported +x86, ARC, NIOS II, Tensilica Xtensa, and RISC-V. The full list of supported boards can be found :ref:`here `. Licensing diff --git a/doc/kernel/overview/source_tree.rst b/doc/kernel/overview/source_tree.rst index 0e65694255e..03ed6ba4157 100644 --- a/doc/kernel/overview/source_tree.rst +++ b/doc/kernel/overview/source_tree.rst @@ -60,6 +60,9 @@ which are not described here. Various programs and other files used to build and test Zephyr applications. +:file:`cmake` + Additional build scripts needed to build Zephyr. + :file:`subsys` Subsystems of Zephyr, including: diff --git a/doc/subsystems/test/ztest.rst b/doc/subsystems/test/ztest.rst index 1b460fd5867..a44a2be238f 100644 --- a/doc/subsystems/test/ztest.rst +++ b/doc/subsystems/test/ztest.rst @@ -23,10 +23,10 @@ the **bar** component of **foo**, you should copy the sample folder to The sample contains the following files: -Makefile +CMakeLists.txt -.. literalinclude:: ../../../samples/testing/integration/Makefile - :language: Make +.. literalinclude:: ../../../samples/testing/integration/CMakeLists.txt + :language: CMake :linenos: sample.yaml @@ -41,12 +41,6 @@ prj.conf :language: text :linenos: -src/Makefile - -.. literalinclude:: ../../../samples/testing/integration/src/Makefile - :language: Make - :linenos: - src/main.c .. literalinclude:: ../../../samples/testing/integration/src/main.c @@ -79,10 +73,10 @@ that interaction. The :file:`samples/testing/unit` folder contains an example for testing the net-buf api of Zephyr. -Makefile +CMakeLists.txt -.. literalinclude:: ../../../samples/testing/unit/Makefile - :language: Make +.. literalinclude:: ../../../samples/testing/unit/CMakeLists.txt + :language: CMake :linenos: sample.yaml