doc: getting_started: Support multi-OS instructions

In order to be able to document the build on Windows and UNIX
systems, slight variations are required on the app commands
that are used throughout the documentation system.

This includes getting rid of the prompt symbol and providing commands
for both UNIX and Windows operating systems.

Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>

boards/arm/qemu_cortex_m3/doc/board.rst

@@ -73,6 +73,7 @@ emulated environment, for example, with the :ref:`synchronization_sample`:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/synchronization
+   :host-os: unix
    :board: qemu_cortex_m3
    :goals: run
 

boards/x86/qemu_x86/doc/board.rst

@@ -82,6 +82,7 @@ emulated environment. For example, with the :ref:`synchronization_sample`:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/synchronization
+   :host-os: unix
    :board: qemu_x86
    :goals: run
 

boards/xtensa/qemu_xtensa/doc/board.rst

@@ -17,6 +17,7 @@ emulated environment, for example, with the :ref:`synchronization_sample`:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/synchronization
+   :host-os: unix
    :board: qemu_xtensa
    :goals: run
 

doc/getting_started/getting_started.rst

@@ -20,12 +20,32 @@ using Git to clone the repository anonymously. Enter:
 
 .. code-block:: console
 
-   $ cd ~
-   $ git clone https://github.com/zephyrproject-rtos/zephyr.git
+   # 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
 **********************************
 
@@ -33,7 +53,7 @@ The Zephyr project supports these operating systems:
 
 * Linux
 * macOS
-* Windows 8.1
+* Microsoft Windows
 
 Use the following procedures to create a new development environment.
 
@@ -70,21 +90,28 @@ To build an example application follow these steps:
 
    .. code-block:: console
 
-      $ export ZEPHYR_GCC_VARIANT=zephyr
-      $ export ZEPHYR_SDK_INSTALL_DIR=<sdk installation directory>
+
+      # 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
+      cd zephyr
 
-#. Source the project environment file to set the project environment
-   variables:
+#. Set the project environment variables:
 
    .. code-block:: console
 
-      $ source zephyr-env.sh
+      # 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:
 
@@ -94,6 +121,16 @@ To build an example application follow these steps:
       :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:
 
@@ -109,10 +146,10 @@ of the supported boards:
 
 .. code-block:: console
 
-   $ make usage
+   ninja usage
 
 Sample projects for different features of the project are available at
-at :file:`$ZEPHYR_BASE/samples`.
+at :file:`ZEPHYR_BASE/samples`.
 After building an application successfully, the results can be found in the
 directory where cmake was invoked.
 
@@ -121,7 +158,6 @@ The ELF binaries generated by the build system are named by default
 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
@@ -145,21 +181,29 @@ must be installed.
 
    .. code-block:: console
 
-      $ unset ZEPHYR_GCC_VARIANT
-      $ unset ZEPHYR_SDK_INSTALL_DIR
-      $ cd <zephyr git clone location>
-      $ source zephyr-env.sh
+      # 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%
 
-#. Build Kconfig in :file:`$ZEPHYR_BASE/build` and add it to path
+
+#. 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
+      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::
 
@@ -182,14 +226,18 @@ 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:`~/gcc-arm-none-eabi-5_3-2016q1/`.
+   extracted to: :file:`<user folder>/gcc-arm-none-eabi-5_3-2016q1/`.
 
 #. Build the example :ref:`hello_world` project, enter:
 
    .. code-block:: console
 
-      $ export GCCARMEMB_TOOLCHAIN_PATH="~/gcc-arm-none-eabi-5_3-2016q1/"
-      $ export ZEPHYR_GCC_VARIANT=gccarmemb
+      # 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
@@ -208,12 +256,11 @@ completed.
 To run an application using the x86 emulation board configuration (qemu_x86),
 type:
 
-.. code-block:: console
-
-   $ cd $ZEPHYR_BASE/samples/hello_world
-   $ mkdir qemu_build && cd qemu_build
-   $ cmake -DBOARD=qemu_x86 ..
-   $ make run
+.. 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``.
 
@@ -223,9 +270,6 @@ QEMU is not supported on all boards and SoCs. When developing for a specific
 hardware target you should always test on the actual hardware and should not
 rely on testing in the QEMU emulation environment only.
 
-
-.. _GCC ARM Embedded: https://launchpad.net/gcc-arm-embedded
-
 Running a Sample Application natively (POSIX OS)
 ================================================
 
@@ -236,22 +280,25 @@ natively 64bit.
 
 To compile and run an application in this way, type:
 
-.. code-block:: console
-
-   $ cd $ZEPHYR_BASE/samples/hello_world
-   $ mkdir build && cd build
-   $ cmake -DBOARD=native_posix ..
-   $ make
+.. zephyr-app-commands::
+   :zephyr-app: samples/hello_world
+   :host-os: unix
+   :board: native_posix
+   :goals: build
 
 and then:
 
 .. code-block:: console
 
-   $ make run
+   ninja run
    # or just:
-   $ zephyr/zephyr.exe
+   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
+

doc/getting_started/installation_linux.rst

@@ -29,14 +29,14 @@ before upgrading:
 
 .. code-block:: console
 
-   $ sudo apt-get update
-   $ sudo apt-get upgrade
+   sudo apt-get update
+   sudo apt-get upgrade
 
 On Fedora:
 
 .. code-block:: console
 
-   $ sudo dnf upgrade
+   sudo dnf upgrade
 
 Note that having a newer version available for an installed package
 (and reported by ``dnf check-update``) does not imply a subsequent
@@ -52,7 +52,7 @@ Install the required packages in a Ubuntu host system with:
 
 .. code-block:: console
 
-   $ sudo apt-get install --no-install-recommends git cmake ninja-build gperf \
+   sudo apt-get install --no-install-recommends git cmake ninja-build gperf \
      ccache doxygen dfu-util device-tree-compiler \
      python3-ply python3-pip python3-setuptools xz-utils file make gcc-multilib
 
@@ -60,27 +60,27 @@ Install the required packages in a Fedora host system with:
 
 .. code-block:: console
 
-   $ sudo dnf group install "Development Tools"
-   $ sudo dnf install git cmake ninja-build gperf ccache\
+   sudo dnf group install "Development Tools"
+   sudo dnf install git cmake ninja-build gperf ccache\
 	 doxygen dfu-util dtc python3-pip \
 	 python3-ply python3-yaml dfu-util dtc python3-pykwalify
 
 Install additional packages required for development with Zephyr::
 
-   $ cd ~/zephyr  # or to your directory where zephyr is cloned
-   $ pip3 install --user -r scripts/requirements.txt
+   cd ~/zephyr  # or to your directory where zephyr is cloned
+   pip3 install --user -r scripts/requirements.txt
 
 CMake version 3.8.2 or higher is required. Check what version you have using
 ``cmake --version``, and if its an older version, check the backports or
 install a more recent version manually. For example, to install version
 3.8.2 from the CMake website directly in ~/cmake::
 
-   $ mkdir $HOME/cmake && cd $HOME/cmake
-   $ 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/.zephyrrc
-   $ source <zephyr git clone location>/zephyr-env.sh
-   $ cmake --version
+   mkdir $HOME/cmake && cd $HOME/cmake
+   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/.zephyrrc
+   source <zephyr git clone location>/zephyr-env.sh
+   cmake --version
 
 .. _zephyr_sdk:
 
@@ -120,7 +120,7 @@ Follow these steps to install the SDK on your Linux host system.
 
    .. code-block:: console
 
-      $ wget https://github.com/zephyrproject-rtos/meta-zephyr-sdk/releases/download/0.9.2/zephyr-sdk-0.9.2-setup.run
+      wget https://github.com/zephyrproject-rtos/meta-zephyr-sdk/releases/download/0.9.2/zephyr-sdk-0.9.2-setup.run
 
 #. Run the installation binary, follow this example:
 
@@ -131,7 +131,7 @@ Follow these steps to install the SDK on your Linux host system.
 
    .. code-block:: console
 
-      $ sh zephyr-sdk-<version>-setup.run
+      sh zephyr-sdk-<version>-setup.run
 
    There is no need to use ``sudo`` if the SDK is installed in the current
    user's home directory.
@@ -146,15 +146,15 @@ Follow these steps to install the SDK on your Linux host system.
 
    .. code-block:: console
 
-      $ export ZEPHYR_GCC_VARIANT=zephyr
-      $ export ZEPHYR_SDK_INSTALL_DIR=<sdk installation directory>
+      export ZEPHYR_GCC_VARIANT=zephyr
+      export ZEPHYR_SDK_INSTALL_DIR=<sdk installation directory>
 
   To use the same toolchain in new sessions in the future you can set the
   variables in the file :file:`${HOME}/.zephyrrc`, for example:
 
   .. code-block:: console
 
-     $ cat <<EOF > ~/.zephyrrc
+     cat <<EOF > ~/.zephyrrc
      export ZEPHYR_GCC_VARIANT=zephyr
      export ZEPHYR_SDK_INSTALL_DIR=/opt/zephyr-sdk
      EOF

doc/getting_started/installation_mac.rst

@@ -57,31 +57,31 @@ Install tools to build Zephyr binaries:
 
 .. code-block:: console
 
-   $ brew install cmake ninja dfu-util doxygen qemu dtc python3 gperf
-   $ curl -O 'https://bootstrap.pypa.io/get-pip.py'
-   $ ./get-pip.py
-   $ rm get-pip.py
-   $ cd ~/zephyr   # or to the folder where you cloned the zephyr repo
-   $ pip3 install --user -r scripts/requirements.txt
+   brew install cmake ninja dfu-util doxygen qemu dtc python3 gperf
+   curl -O 'https://bootstrap.pypa.io/get-pip.py'
+   ./get-pip.py
+   rm get-pip.py
+   cd ~/zephyr   # or to the folder where you cloned the zephyr repo
+   pip3 install --user -r scripts/requirements.txt
 
 Source :file:`zephyr-env.sh` wherever you have cloned the Zephyr Git repository:
 
 .. code-block:: console
 
-   $ unset ZEPHYR_SDK_INSTALL_DIR
-   $ cd <zephyr git clone location>
-   $ source zephyr-env.sh
+   unset ZEPHYR_SDK_INSTALL_DIR
+   cd <zephyr git clone location>
+   source zephyr-env.sh
 
 Build Kconfig in :file:`$ZEPHYR_BASE/build` and add it to path
 
 .. code-block:: console
 
-   $ cd $ZEPHYR_BASE
-   $ mkdir build && cd build
-   $ cmake $ZEPHYR_BASE/scripts
-   $ make
-   $ echo "export PATH=$PWD/kconfig:\$PATH" >> $HOME/.zephyrrc
-   $ source $ZEPHYR_BASE/zephyr-env.sh
+   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::
 
@@ -106,9 +106,9 @@ Install tools needed for building the toolchain (if needed):
 
 .. code-block:: console
 
-   $ brew install gettext help2man mpfr gmp coreutils wget
-   $ brew tap homebrew/dupes
-   $ brew install grep --with-default-names
+   brew install gettext help2man mpfr gmp coreutils wget
+   brew tap homebrew/dupes
+   brew install grep --with-default-names
 
 
 To build the toolchain, you will need the latest version of crosstool-ng (1.23).
@@ -117,7 +117,7 @@ however try and see if you get 1.23 installed:
 
 .. code-block:: console
 
-   $ brew install crosstool-ng
+   brew install crosstool-ng
 
 Alternatively you can install the latest version of :program:`crosstool-ng`
 from source. Download the latest version from the `crosstool-ng site`_. The
@@ -125,12 +125,12 @@ latest version usually supports the latest released compilers.
 
 .. code-block:: console
 
-   $ wget http://crosstool-ng.org/download/crosstool-ng/crosstool-ng-1.23.0.tar.bz2
-   $ tar xvf crosstool-ng-1.23.0.tar.bz2
-   $ cd crosstool-ng-1.23.0/
-   $ ./configure
-   $ make
-   $ make install
+   wget http://crosstool-ng.org/download/crosstool-ng/crosstool-ng-1.23.0.tar.bz2
+   tar xvf crosstool-ng-1.23.0.tar.bz2
+   cd crosstool-ng-1.23.0/
+   ./configure
+   make
+   make install
 
 Creating a Case-sensitive File System
 =====================================
@@ -158,9 +158,9 @@ When mounted, the file system of the image will be available under
 
 .. code-block:: console
 
-   $ cd /Volumes/CrossToolNG
-   $ mkdir build
-   $ cd build
+   cd /Volumes/CrossToolNG
+   mkdir build
+   cd build
 
 Setting the Toolchain Options
 =============================
@@ -179,15 +179,15 @@ Currently the following configurations are provided:
 
 .. code-block:: console
 
-   $ cp ${ZEPHYR_BASE}/scripts/cross_compiler/i586.config .config
+   cp ${ZEPHYR_BASE}/scripts/cross_compiler/i586.config .config
 
 You can create a toolchain configuration or customize an existing configuration
 yourself using the configuration menus:
 
 .. code-block:: console
 
-   $ export CT_PREFIX=/Volumes/CrossToolNG
-   $ ct-ng oldconfig
+   export CT_PREFIX=/Volumes/CrossToolNG
+   ct-ng oldconfig
 
 Verifying the Configuration of the Toolchain
 ============================================
@@ -220,7 +220,7 @@ To build the toolchain, enter:
 
 .. code-block:: console
 
-   $ ct-ng build
+   ct-ng build
 
 The above process takes a while. When finished, the toolchain will be available
 under :file:`/Volumes/CrossToolNG/x-tools`.
@@ -232,8 +232,8 @@ and use the target location where the toolchain was installed, type:
 
 .. code-block:: console
 
-   $ export ZEPHYR_GCC_VARIANT=xtools
-   $ export XTOOLS_TOOLCHAIN_PATH=/Volumes/CrossToolNG/x-tools
+   export ZEPHYR_GCC_VARIANT=xtools
+   export XTOOLS_TOOLCHAIN_PATH=/Volumes/CrossToolNG/x-tools
 
 
 To use the same toolchain in new sessions in the future you can set the
@@ -241,7 +241,7 @@ variables in the file :file:`${HOME}/.zephyrrc`, for example:
 
 .. code-block:: console
 
-   $ cat <<EOF > ~/.zephyrrc
+   cat <<EOF > ~/.zephyrrc
    export XTOOLS_TOOLCHAIN_PATH=/Volumes/CrossToolNG/x-tools
    export ZEPHYR_GCC_VARIANT=xtools
    EOF

doc/getting_started/installation_win.rst

@@ -44,8 +44,8 @@ packages from their respective websites.
 #. If you're behind a corporate firewall, you'll likely need to specify a
    proxy to get access to internet resources::
 
-      > set HTTP_PROXY=http://user:password@proxy.mycompany.com:1234
-      > set HTTPS_PROXY=http://user:password@proxy.mycompany.com:1234
+      set HTTP_PROXY=http://user:password@proxy.mycompany.com:1234
+      set HTTPS_PROXY=http://user:password@proxy.mycompany.com:1234
 
 #. Install :program:`Chocolatey` by following the instructions on the
    `Chocolatey install`_ website.
@@ -57,20 +57,20 @@ packages from their respective websites.
 
    .. code-block:: console
 
-      > choco feature enable -n allowGlobalConfirmation
+      choco feature enable -n allowGlobalConfirmation
 
 #. Install CMake and DTC:
 
    .. code-block:: console
 
-      > choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System'
-      > choco install dtc-msys2 --version 1.4.4
+      choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System'
+      choco install dtc-msys2 --version 1.4.4
 
 #. Install the rest of the tools:
 
    .. code-block:: console
 
-      > choco install git python ninja gperf
+      choco install git python ninja gperf
 
 #. Close the Command Prompt window.
 
@@ -80,13 +80,13 @@ packages from their respective websites.
 
    .. code-block:: console
 
-      > cd %userprofile%
-      > git clone https://github.com/zephyrproject-rtos/zephyr.git
+      cd %userprofile%
+      git clone https://github.com/zephyrproject-rtos/zephyr.git
 
 #. Install the required Python modules::
 
-      > cd %userprofile%\zephyr
-      > pip install --user -r scripts/requirements.txt
+      cd %userprofile%\zephyr
+      pip install --user -r scripts/requirements.txt
 
 #. The build system should now be ready to work with any toolchain installed in
    your system. In the next step you'll find instructions for installing
@@ -118,8 +118,8 @@ packages from their respective websites.
 
    .. code-block:: console
 
-      > set ZEPHYR_GCC_VARIANT=issm
-      > set ISSM_INSTALLATION_PATH=c:\issm0-toolchain-windows-2017-01-25
+      set ZEPHYR_GCC_VARIANT=issm
+      set ISSM_INSTALLATION_PATH=c:\issm0-toolchain-windows-2017-01-25
 
    Use the path where you extracted the ISSM toolchain.
 
@@ -127,15 +127,15 @@ packages from their respective websites.
 
    .. code-block:: console
 
-      > set ZEPHYR_GCC_VARIANT=gccarmemb
-      > set GCCARMEMB_TOOLCHAIN_PATH=c:\gccarmemb
+      set ZEPHYR_GCC_VARIANT=gccarmemb
+      set GCCARMEMB_TOOLCHAIN_PATH=c:\gccarmemb
 
    And for either, set the `ZEPHYR_BASE` environment variable to the root
    of the Zephyr repository you cloned:
 
    .. code-block:: console
 
-      > set ZEPHYR_BASE=%userprofile%\zephyr
+      set ZEPHYR_BASE=%userprofile%\zephyr
 
 #. Finally, you can try building the :ref:`hello_world` sample to check things
    out.
@@ -144,6 +144,7 @@ packages from their respective websites.
 
    .. zephyr-app-commands::
      :zephyr-app: samples/hello_world
+     :host-os: win
      :generator: ninja
      :board: arduino_101
      :goals: build
@@ -152,6 +153,7 @@ packages from their respective websites.
 
    .. zephyr-app-commands::
      :zephyr-app: samples/hello_world
+     :host-os: win
      :generator: ninja
      :board: nrf52_pca10040
      :goals: build
@@ -194,16 +196,16 @@ environment for Windows. Follow the steps below to set it up:
 #. If you're behind a corporate firewall, you'll likely need to specify a
    proxy to get access to internet resources::
 
-      $ export http_proxy=http://proxy.mycompany.com:123
-      $ export https_proxy=$http_proxy
+      export http_proxy=http://proxy.mycompany.com:123
+      export https_proxy=$http_proxy
 
 #. Update MSYS2's packages and install the dependencies required to build
    Zephyr (you may need to restart the MSYS2 shell):
 
    .. code-block:: console
 
-      $ pacman -Syu
-      $ pacman -S git cmake make gcc dtc diffutils ncurses-devel python3 gperf
+      pacman -Syu
+      pacman -S git cmake make gcc dtc diffutils ncurses-devel python3 gperf
 
 #. From within the MSYS2 MSYS Shell, clone a copy of the Zephyr source
    into your home directory using Git.  (Some Zephyr tools require
@@ -213,16 +215,16 @@ environment for Windows. Follow the steps below to set it up:
 
    .. code-block:: console
 
-      $ cd ~
-      $ git clone --config core.autocrlf=false https://github.com/zephyrproject-rtos/zephyr.git
+      cd ~
+      git clone --config core.autocrlf=false https://github.com/zephyrproject-rtos/zephyr.git
 
 #. Install pip and the required Python modules::
 
-      $ curl -O 'https://bootstrap.pypa.io/get-pip.py'
-      $ ./get-pip.py
-      $ rm get-pip.py
-      $ cd ~/zephyr   # or to the folder where you cloned the zephyr repo
-      $ pip install --user -r scripts/requirements.txt
+      curl -O 'https://bootstrap.pypa.io/get-pip.py'
+      ./get-pip.py
+      rm get-pip.py
+      cd ~/zephyr   # or to the folder where you cloned the zephyr repo
+      pip install --user -r scripts/requirements.txt
 
 #. The build system should now be ready to work with any toolchain installed in
    your system. In the next step you'll find instructions for installing
@@ -237,8 +239,8 @@ environment for Windows. Follow the steps below to set it up:
      You'll need the tar application to unpack this file. In an ``MSYS2 MSYS``
      console, install ``tar`` and use it to extract the toolchain archive::
 
-        $ pacman -S tar
-        $ tar -zxvf /c/Users/myusername/Downloads/issm-toolchain-windows-2017-01-15.tar.gz -C /c
+        pacman -S tar
+        tar -zxvf /c/Users/myusername/Downloads/issm-toolchain-windows-2017-01-15.tar.gz -C /c
 
      substituting the .tar.gz path name with the one you downloaded.
 
@@ -261,8 +263,8 @@ environment for Windows. Follow the steps below to set it up:
 
    .. code-block:: console
 
-      $ export ZEPHYR_GCC_VARIANT=issm
-      $ export ISSM_INSTALLATION_PATH=/c/issm0-toolchain-windows-2017-01-25
+      export ZEPHYR_GCC_VARIANT=issm
+      export ISSM_INSTALLATION_PATH=/c/issm0-toolchain-windows-2017-01-25
 
    Use the path where you extracted the ISSM toolchain.
 
@@ -270,29 +272,29 @@ environment for Windows. Follow the steps below to set it up:
 
    .. code-block:: console
 
-      $ export ZEPHYR_GCC_VARIANT=gccarmemb
-      $ export GCCARMEMB_TOOLCHAIN_PATH=/c/gccarmemb
+      export ZEPHYR_GCC_VARIANT=gccarmemb
+      export GCCARMEMB_TOOLCHAIN_PATH=/c/gccarmemb
 
    And for either, run the provided script to set up zephyr project specific
    variables:
 
    .. code-block:: console
 
-      $ unset ZEPHYR_SDK_INSTALL_DIR
-      $ cd <zephyr git clone location>
-      $ source zephyr-env.sh
+      unset ZEPHYR_SDK_INSTALL_DIR
+      cd <zephyr git clone location>
+      source zephyr-env.sh
 
 #. Within the MSYS console, 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
+      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::
 
@@ -306,6 +308,7 @@ To build for the Intel |reg| Quark |trade| (x86-based) Arduino 101:
 .. zephyr-app-commands::
   :zephyr-app: samples/hello_world
   :board: arduino_101
+  :host-os: win
   :goals: build
 
 To build for the ARM-based Nordic nRF52 Development Kit:
@@ -313,6 +316,7 @@ To build for the ARM-based Nordic nRF52 Development Kit:
 .. zephyr-app-commands::
   :zephyr-app: samples/hello_world
   :board: nrf52_pca10040
+  :host-os: win
   :goals: build
 
 This should check that all the tools and toolchain are set up correctly for

doc/subsystems/bluetooth/devel.rst

@@ -52,7 +52,7 @@ through a so-called user channel for QEMU to use:
 
    .. code-block:: console
 
-      $ sudo tools/btproxy -u
+      sudo tools/btproxy -u
       Listening on /tmp/bt-server-bredr
 
 #. Choose one of the Bluetooth sample applications located in

doc/subsystems/networking/qemu_setup.rst

@@ -19,9 +19,9 @@ in a separate git repository:
 
 .. code-block:: console
 
-   $ git clone https://github.com/zephyrproject-rtos/net-tools
-   $ cd net-tools
-   $ make
+   git clone https://github.com/zephyrproject-rtos/net-tools
+   cd net-tools
+   make
 
 .. note::
 
@@ -48,7 +48,7 @@ In terminal #2, type:
 
 .. code-block:: console
 
-   $ ./loop-socat.sh
+   ./loop-socat.sh
 
 Step 2 - Start TAP device routing daemon
 ========================================
@@ -58,7 +58,7 @@ In terminal #3, type:
 
 .. code-block:: console
 
-   $ sudo ./loop-slip-tap.sh
+   sudo ./loop-slip-tap.sh
 
 
 Step 3 - Start app in QEMU
@@ -88,19 +88,19 @@ You can start with pings:
 
 .. code-block:: console
 
-   $ ping 192.0.2.1
-   $ ping6 2001:db8::1
+   ping 192.0.2.1
+   ping6 2001:db8::1
 
 For example, using netcat ("nc") utility, connecting using UDP:
 
 .. code-block:: console
 
-   $ echo foobar | nc -6 -u 2001:db8::1 4242
+   echo foobar | nc -6 -u 2001:db8::1 4242
    foobar
 
 .. code-block:: console
 
-   $ echo foobar | nc -u 192.0.2.1 4242
+   echo foobar | nc -u 192.0.2.1 4242
    foobar
 
 If echo_server is compiled with TCP support (now enabled by default for
@@ -108,7 +108,7 @@ echo_server sample, CONFIG_NET_TCP=y):
 
 .. code-block:: console
 
-   $ echo foobar | nc -6 -q2 2001:db8::1 4242
+   echo foobar | nc -6 -q2 2001:db8::1 4242
    foobar
 
 .. note::
@@ -149,7 +149,7 @@ used, the following command should be run as root:
 
 .. code-block:: console
 
-   $ iptables -t nat -A POSTROUTING -j MASQUERADE -s 192.0.2.1
+   iptables -t nat -A POSTROUTING -j MASQUERADE -s 192.0.2.1
 
 Additionally, IPv4 forwarding should be enabled on host, and you may need to
 check that other firewall (iptables) rules don't interfere with masquerading.
@@ -166,8 +166,8 @@ Terminal #1:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/net/echo_server
-   :board: qemu_x86
    :host-os: unix
+   :board: qemu_x86
    :goals: build
    :build-args: server
    :compact:
@@ -179,8 +179,8 @@ Terminal #2:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/net/echo_client
-   :board: qemu_x86
    :host-os: unix
+   :board: qemu_x86
    :goals: build
    :build-args: client
    :compact:
@@ -203,18 +203,18 @@ Terminal #1:
 
 .. code-block:: console
 
-   $ socat PTY,link=/tmp/slip.devMAIN UNIX-LISTEN:/tmp/slip.sockMAIN
-   $ $ZEPHYR_BASE/../net-tools/tunslip6 -t tapMAIN -T -s /tmp/slip.devMAIN \
+   socat PTY,link=/tmp/slip.devMAIN UNIX-LISTEN:/tmp/slip.sockMAIN
+   $ZEPHYR_BASE/../net-tools/tunslip6 -t tapMAIN -T -s /tmp/slip.devMAIN \
         2001:db8::1/64
    # Now run Zephyr
-   $ make run QEMU_INSTANCE=MAIN
+   make run QEMU_INSTANCE=MAIN
 
 Terminal #2:
 ============
 
 .. code-block:: console
 
-   $ socat PTY,link=/tmp/slip.devOTHER UNIX-LISTEN:/tmp/slip.sockOTHER
-   $ $ZEPHYR_BASE/../net-tools/tunslip6 -t tapOTHER -T -s /tmp/slip.devOTHER \
+   socat PTY,link=/tmp/slip.devOTHER UNIX-LISTEN:/tmp/slip.sockOTHER
+   $ZEPHYR_BASE/../net-tools/tunslip6 -t tapOTHER -T -s /tmp/slip.devOTHER \
         2001:db8::1/64
-   $ make run QEMU_INSTANCE=OTHER
+   make run QEMU_INSTANCE=OTHER

doc/tools/opensda.rst

@@ -141,7 +141,7 @@ open telnet:
 
   .. code-block:: console
 
-     $ telnet localhost 19021
+     telnet localhost 19021
      Trying 127.0.0.1...
      Connected to localhost.
      Escape character is '^]'.

samples/hello_world/README.rst

@@ -19,6 +19,7 @@ on QEMU as follows:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/hello_world
+   :host-os: unix
    :board: qemu_x86
    :goals: run
    :compact:
@@ -28,6 +29,7 @@ single thread: :file:`prj_single.conf`:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/hello_world
+   :host-os: unix
    :board: qemu_x86
    :conf: prj_single.conf
    :goals: run

samples/net/dhcpv4_client/README.rst

@@ -51,6 +51,7 @@ Run Zephyr samples/net/dhcpv4_client application in QEMU:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/net/dhcpv4_client
+   :host-os: unix
    :board: qemu_x86
    :goals: run
    :compact:
@@ -120,6 +121,7 @@ Build Zephyr samples/net/dhcpv4_client application:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/net/dhcpv4_client
+   :host-os: unix
    :board: frdm_k64f
    :goals: build flash
    :compact:

samples/net/echo_client/README.rst

@@ -89,6 +89,7 @@ Run echo-client application in QEMU:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/net/echo_client
+   :host-os: unix
    :board: qemu_x86
    :goals: run
    :compact:

samples/net/echo_server/README.rst

@@ -88,6 +88,7 @@ Run echo-server application in QEMU:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/net/echo_server
+   :host-os: unix
    :board: qemu_x86
    :goals: run
    :compact:

samples/net/http_server/README.rst

@@ -62,6 +62,7 @@ locate the source code of this sample application and type:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/net/http_server
+   :host-os: unix
    :board: qemu_x86
    :goals: run
    :compact:
@@ -180,6 +181,7 @@ In order to compile and run the code execute:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/net/http_server
+   :host-os: unix
    :board: qemu_x86
    :conf: prj_tls.conf
    :goals: run

samples/net/lwm2m_client/README.rst

@@ -67,6 +67,7 @@ Build the lwm2m-client sample application for QEMU like this:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/net/lwm2m_client
+   :host-os: unix
    :board: qemu_x86
    :goals: run
    :compact:
@@ -87,6 +88,7 @@ To build the lwm2m-client sample for QEMU with DTLS support do the following:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/net/lwm2m_client
+   :host-os: unix
    :board: qemu_x86
    :conf: prj_dtls.conf
    :goals: run

samples/net/telnet/README.rst

@@ -33,6 +33,7 @@ Run Zephyr samples/net/telnet application in QEMU:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/net/telnet
+   :host-os: unix
    :board: qemu_x86
    :goals: run
    :compact:

samples/philosophers/README.rst

@@ -45,6 +45,7 @@ on QEMU as follows:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/philosophers
+   :host-os: unix
    :board: qemu_x86
    :goals: run
    :compact:

samples/subsys/console/getchar/README.rst

@@ -31,6 +31,7 @@ The easiest way to run this sample is using QEMU:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/subsys/console/getchar
+   :host-os: unix
    :board: qemu_x86
    :goals: run
    :compact:

samples/subsys/console/getline/README.rst

@@ -31,6 +31,7 @@ The easiest way to run this sample is using QEMU:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/subsys/console/getline
+   :host-os: unix
    :board: qemu_x86
    :goals: run
    :compact:

samples/subsys/logging/kernel_event_logger/README.rst

@@ -24,6 +24,7 @@ on QEMU as follows:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/subsys/logging/kernel_event_logger
+   :host-os: unix
    :board: qemu_x86
    :goals: run
    :compact:

samples/synchronization/README.rst

@@ -20,6 +20,7 @@ on QEMU as follows:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/synchronization
+   :host-os: unix
    :board: qemu_x86
    :goals: run
    :compact: