qpc-rtthread/doxygen/exa_os.dox

/*! @page exa_os Examples for Workstations (Windows/POSIX)

<p>The examples in the <span class="img folder">qpc/examples/workstation</span> directory are designed for workstations (running Windows, Linux, or MacOS). Currently, the following examples are provided:
</p>

- <span class="img folder">blinky</span> &mdash; Simple "Blinky" active object (command-line)
- <span class="img folder">calc</span> &mdash; Calculator example from Chapter 2 of [PSiCC2](https://www.state-machine.com/psicc2)
- <span class="img folder">calc1</span> &mdash; Improved Calculator example from Chapter 2 of [PSiCC2](https://www.state-machine.com/psicc2)
- <span class="img folder">calc1_sub</span> &mdash; Calculator example with sub-machines
- <span class="img folder">comp</span> &mdash; Orthogonal Component design pattern
- <span class="img folder">defer</span> &mdash; Deferred Event design pattern
- <span class="img folder">dpp</span> &mdash; DPP application from Chapter 9 of [PSiCC2](https://www.state-machine.com/psicc2) (**Spy**)
- <span class="img folder">dpp_comp</span> &mdash; DPP with Orthogonal-Component pattern (**Spy**)
- <span class="img folder">dpp-gui</span> &mdash; DPP (with GUI on Windows) (**Spy**)
- <span class="img folder">game-gui</span> &mdash; "Fly 'n' Shoot" game from Chapter 1 of [PSiCC2](https://www.state-machine.com/psicc2) (**Spy**)
- <span class="img folder">history_qhsm</span> &mdash; Transition-to-History (with ::QHsm class)
- <span class="img folder">history_qmsm</span> &mdash; Transition-to-History (with ::QMsm class)
- <span class="img folder">qhsmtst</span> &mdash; Test State Machine based on ::QHsm from Chapter 2 of [PSiCC2](https://www.state-machine.com/psicc2) (**Spy**)
- <span class="img folder">qmsmtst</span> &mdash; Test State Machine based on ::QMsm (**Spy**)
- <span class="img folder">reminder</span> &mdash; Reminder design pattern from Chapter 5 of PSiCC2
- <span class="img folder">reminder2</span> &mdash; Reminder design pattern different version

@remark
The examples marked with (**Spy**) provide the @ref exa_os-spy "Spy Configuration".



@section exa_win_posix Windows and POSIX Workstations
All examples in the <span class="img folder">qpc/examples/workstation</span> directory work both on Windows as well as on POSIX (Linux, MacOS). On each of these operating systems you use the same cross-platform `Makefile` co-located with each example. The provided cross-platform `Makefiles` assume the **GNU GCC toolchain**. The `Makefile` discovers the host operating system and chooses the appropriate QP port version:

- On Windows &mdash; @ref win32 "win32" or @ref win32-qv "win32-qv"; and
- On POSIX &mdash; @ref posix "posix" or @ref posix-qv "posix-qv" (Linux, MacOS, etc.)

@note
On Windows, the **make** utility and the GNU GCC toolchain (**MinGW**) are provided in the [<b>QTools collection</b>](https://www.state-machine.com/qtools), which is available for a separate download. The code can be also built with other tools as well, such as the Microsoft Visual Studio 2013 and newer.


@image html  blinky_win32.png
@image latex blinky_win32.png width=4.0in
@caption{Blinky example on Windows}

<br>
@image html  blinky_posix.png
@image latex blinky_posix.png width=4.0in
@caption{Blinky example on Linux}


@section exa_os-qv Single-Threaded and Multi-Threaded QP/C Ports
Each of the examples can be linked to either the single-threaded QP/C ports (@ref win32-qv or @ref posix-qv) or multi-threaded ports (@ref win32 or @ref posix). The choice is made in the `Makefiles`, by editing the line, which defines the `QP_PORT_DIR` symbol. For instance, the following lines select the @ref win32-qv port and leave the @ref win32 port commented-out:

<br>
@verbatim
QP_PORT_DIR := $(QPC)/ports/win32-qv
#QP_PORT_DIR := $(QPC)/ports/win32
@endverbatim

To reverse the selection, you need to move the comment `#` character.

@remarks
The single-threaded QP/C ports (@ref win32-qv "win32-qv" and @ref posix-qv "posix-qv") are recommended for **emulating** software intended for deeply-embedded targets ("dual-targeting" the embedded software development).@n


@attention
Examples in the <span class="img folder">workstation</span> directory can also be used on the **embedded versions** of the desktop operating systems, such as **Embedded Linux** and **Windows Embedded**. For the embedded applications, the **multi-threaded** @ref ports_os "QP ports" ( @ref posix "posix" and @ref win32 "win32", respectively) are recommended.



@section exa_os_conf Debug, Release, and Spy Build Configurations
The `Makefiles` for the examples generally support the following three build configurations.



@subsection exa_os-dbg Debug Configuration
This is the default build configuration, with full debugging information and minimal optimization. To build this configuration, type:

<br>
@verbatim
make
@endverbatim

To clean this build, type

@verbatim
make clean
@endverbatim

The object files and the executable is located in the <span class="img folder">build</span> sub-directory.



@subsection exa_os-rel Release Configuration
This configuration is built with no debugging information and high optimization. Single-stepping and debugging might be difficult due
to the lack of debugging information and optimized code. To build this configuration, type:

@verbatim
make CONF=rel
@endverbatim

To clean this build, type

@verbatim
make CONF=rel clean
@endverbatim

The object files and the executable is located in the <span class="img folder">build_rel</span> directory.


@subsection exa_os-spy Spy Configuration
This configuration is built with the QP's Q-SPY trace functionality. The QP/Spy output is performed by a TCP/IP socket and requires launching the QSPY host application with the -t option. To build this configuration, type:

@verbatim
make CONF=spy
@endverbatim

To clean this build, type

@verbatim
make CONF=spy clean
@endverbatim

The object files and the executable are located in the <span class="img folder">build_spy</span> sub-directory.

@note
The Spy build configuration requires launching the [QSPY host utility](https://www.state-machine.com/qtools/qspy.html) with the `-t` command-line option **before** running the example. This is so that the example code can output the QS software tracing to the TCP/IP socket of QSPY.


@remark
Only specific examples support the Spy build configuration. The examples that don't support it, will report an error or will fail the linking stage.

@image html  dpp_win.png
@image latex dpp_win.png width=5.0in
@caption{DPP with QSPY example on Windows (QSPY running in a separate command-prompt)}

<br>
@image html  dpp_posix.png
@image latex dpp_posix.png width=6.0in
@caption{DPP with QSPY example on Linux (QSPY running in a separate command-prompt)}

@ifnot LATEX
@nav_next{exa_mware}
@endif
*/