README ====== This directory contains a collection of Unit Tests that can be used to verify NXWidgets.: Contents ======== o Installing and Building the Unit Tests 1. Setup NuttX a) Configure NuttX b) Enable C++ Support c) Enable Debug Options d) NxWM e) Other Possible .config file changes f) Other Possible .config file changes 2. Configure in the Selected Unit Test o Work-Arounds 1. Build Issues 2. Stack Size Issues with the X11 Simulation o Theory of Operation o Unit Test Directories o Example Installing and Building the Unit Tests ====================================== 1. Setup NuttX a) Configure NuttX Configure NuttX to run one of the target configurations. For example, let's assume that you are using the sim/nsh2 configuration. The sim/nsh2 configuration was specially created for use NXWidgets on the simulation platform. A similar, special configuration stm3210e-eval/nsh2 is also for the STM3210E-EVAL available. However, the unit test can be run on other configurations (see steps d and e below). NOTE: There are some other special configurationsrecommended for unit-leveling testing of NxWM because the configuration is more complex in that case. These are: 1) sim/nxwmm, or the simulated platform (no touchscreen), and 2) stm3240g-evel, for the STM3240G-EVAL board (with the STMPE11 touchscreen) We will assume the sim/nsh2 configuration in this discussion. The sim/nsh2 configuration is installed as follows: cd make distclean cd tools ./configure.sh sim/nsh2 Where: is the full, absolute path to the NuttX build directory If you are using the sim/nsh2 or stm3210e-eval configurations, then skip to step 2 (Hmmm.. better check 1d) too). There may be certain requirements for the configuration that you select... for example, certain widget tests may require touchscreen support or special font selections. These test-specific requirements are addressed below under "Unit Test Directories" b) Enable C++ Support If you are not using the sim/nsh2 or stm3210e-eval, you will need to add the following definitions to the NuttX configuration at nuttx/.config to enable C++ support: CONFIG_HAVE_CXX=y Check first, some configurations already have C++ support enabled (As of this writing *ONLY* the sim/nsh2 and stm321-e-eval configurations have C++ support pre-enabled). c) Enable Debug Options If you are running on a simulated target, then you might also want to enable debug symbols: CONFIG_DEBUG_SYMBOLS=y Then you can run the simulation using GDB or DDD which is a very powerful debugging environment! d) Special configuration requirements for the nxwm unit test: CONFIG_NXTERM=y CONFIG_NX_MULTIUSER=y e) Other .config file changes -- NSH configurations only. If the configuration that you are using supports NSH and NSH built-in tasks then all is well. If it is an NSH configuration, then you will have to define the following in your nuttx/.config file as well (if it is not already defined): CONFIG_NSH_BUILTIN_APPS=y sim/nsh2 and stm3210e-eval/nsh2 already has this setting. You do not need to change anything further in the nuttx/.config file if you are using either of these configurations. f) Other .config file changes -- NON-NSH configurations only. Entry Point. You will need to set the entry point in the .config file. For NSH configurations, the entry point will always be "nsh_main" and you will see that setting like: CONFIG_USER_ENTRYPOINT="nsh_main" If you are not using in NSH, then each unit test has a unique entry point. That entry point is the name of the unit test directory in all lower case plus the suffix "_main". So, for example, the correct entry for the UnitTests/CButton would be: CONFIG_USER_ENTRYPOINT="cbutton_main" And the correct entry point for UnitTests/nxwm would be: CONFIG_USER_ENTRYPOINT="nxwm_main" etc. For non-NSH configurations (such as the sim/touchscreen) you will have to remove the configuration setting that provided the "main" function so that you use the "main" in the unit test code instead. So, for example, with the sim/touchscreen configuration you need to remove the following from the NuttX configuration file (.config): CONFIG_EXAMPLES_TOUSCHCREEN=y ## REMOVE (provided "tc_main") The following step will then install the new, correct directory containing the user_start function for the selected unit test. If you see that NSH is configured: CONFIG_EXAMPLES_NSH=y ## DO NOT REMOVE Then go back and re-read e) above. sim/nsh2 and stm3210e-eval/nsh2 are both NSH configurations. You do not need to change anything further in the .config file for any NSH configuration. 2. Configure/Install the Selected Unit Test Then reconfigure that to use the Unit Test of your choice: cd /tools ./install.sh Where: is the full, absolute path to the NuttX apps/ directory is the name of a sub-directory in the UnitTests directory 3. Instantiate the Configuration Before we can make the NXWidgets Library, we have to instantiate the NuttX configuration with the installed unit test: cd . ./setenv.sh make context This will create auto-generated files and will setup symbolic links needed in order to build the NXWidgets Library. 4. Adjust the Stack Size If using an simulation configuration (like sim/nsh2) and your unit test uses X11 as its display device, then you would have to increase the size of unit test stack as described below under "Stack Size Issues with the X11 Simulation." 5. Build the NXWidgets Library cd /libnxwidgets make TOPDIR= 6. Build the NxWM library. The NxWM library (libnxwm.a) is required only for the NxWM unit test at NxWidgets/UnitTests/nxwm. For other unit tests, skip to step 7. cd /nxwm make TOPDIR= 7. Build NuttX including the unit test and the NXWidgets library cd . ./setenv.sh make Work-Arounds ============ Build Issues ------------ 1. I have seen this error on Cygwin building C++ code: LD: nuttx.rel ld: skipping incompatible /home/patacongo/projects/nuttx/nuttx/trunk/nuttx/libxx//liblibxx.a when searching for -llibxx ld: cannot find -llibxx The problem seems to be caused because gcc build code for 32-bit mode and g++ builds code for 64-bit mode. Add the -m32 option to the g++ command line seems to fix the problem. In Make.defs: CXXFLAGS = -m32 $(ARCHWARNINGSXX) $(ARCHOPTIMIZATION) \ $(ARCHCPUFLAGSXX) $(ARCHINCLUDESXX) $(ARCHDEFINES) $(EXTRADEFINES) -pipe 2. Stack Size Issues with the X11 Simulation When you run the NuttX simulation, it uses stacks allocated by NuttX from the NuttX heap. The memory management model is exactly the same in the simulation as it is real, target system. This is good because this produces a higher fidelity simulation. However, when the simulation calls into Linux/Cygwin libraries, it will still use these small simulation stacks. This happens, for example, when you call into the system to get and put characters to the console window or when you make x11 calls into the system. The programming model within those libraries will assume a Linux/Cygwin environment where the stack size grows dynamically As a consequence, those system libraries may allocate large data structures on the stack and overflow the small NuttX stacks. X11, in particular, requires large stacks. If you are using X11 in the simulation, make sure that you set aside a "lot" of stack for the X11 system calls (maybe 8 or 16Kb). The stack size for the thread that begins with user start is controlled by the configuration setting CONFIG_USERMAIN_STACKSIZE; you may need to increase this value to larger number to survive the X11 system calls. If you are running X11 applications as NSH add-on programs, then the stack size of the add-on program is controlled in another way. Here are the steps for increasing the stack size in that case: cd ../apps/namedapps # Go to the namedapps directory vi namedapps_list.h # Edit this file and increase the stack size of the add-on rm .built *.o # This will force the namedapps logic to rebuild Theory Of Operation =================== The NuttX application Makefile at apps/Makefile has some special hooks for building "external" applications. In particular, it will automatically build in the contents any directory call "external/" that may appear in the apps/ directory. There is no external/ directory in the repository. Rather, this directory may be provided by the user (possibly as a symbolic link) to add libraries and applications to the standard build from the repository. The script at tools/install.sh, then, just does a lot of careful validation and sanity checking. Then it installs the UnitTest test sub-directory in the apps/ directory by creating a symbolic link in the apps/ directory call "external". That symbolic link will refer to the selected UnitTest sub-directory. UnitTests ========= The following provide simple unit tests for each of the NXWidgets. In addition, these unit tests provide examples for the use of each widget type. CButton Exercises the CButton widget Depends on CLabel CButtonArray Exercises the CButtonArray widget CCheckBox Exercises the CCheckBox widget Depends on CLabel and CButton. CGlyphButton Exercises the CGlyphButton widget. Depends on CLabel and CButton. CImage Exercises the CImage widget CLabel Exercises the CLabel widget CProgressBar Exercises the CProgressBar widget CRadioButton Exercises the CRadioButton and CRadioButtonGroup widgets. Depends on CLabel and CButton CScrollBarHorizontal Exercises the ScrollbarHorizontal Depends on CSliderHorizontal and CGlyphButton CScrollBarVertical Exercises the ScrollbarHorizontal Depends on CSliderVertical and CGlyphButton CSliderHorizontal Exercises the CSliderHorizontal Depends on CSliderHorizontalGrip CSliderVertical Exercises the CSliderVertical Depends on CSliderVerticalGrip CTextBox Exercises the CTextBox widget Depends on CLabel nxwm Exercises the NxWM window manager. Use the special configurations nuttx/configs/sim/nxwm or nuttx/configs/stm3240g-eval/nxwm. Example ======= 1. Configure sim/nsh2 Where: nuttx and nuttx/tools directory $ cd tools/ $ ./configure.sh sim/nsh2 $ cd - 2. Edit the NuttX .config file to enable C++ support Do nothing... sim/nsh2 already has C++ support enabled. Since this is an NSH configuration, the entry point does not need to be changed. 3. Install the CButton C++ application (for example) Where: /tool $ ./install.sh ~/projects/nuttx/nuttx/trunk/apps/ CButton /home/patacongo/projects/nuttx/nuttx/trunk/apps//external already exists... Removing the old symbolic link. Creating symbolic link - To /home/patacongo/projects/nuttx/nuttx/trunk/NxWidgets/UnitTests/CButton - At /home/patacongo/projects/nuttx/nuttx/trunk/apps//external 4. Instantiate the Configuration Where: nuttx directory $ cd /home/patacongo/projects/nuttx/nuttx/trunk/nuttx $ . ./setenv.sh $ make context This will create auto-generated files and will setup symbolic links needed in order to build the NXWidgets Library. 6. Adjust the Stack Size If using an simulation configuration (like sim/nsh2) and your unit test uses X11 as its display device, then you would have to increase the size of unit test stack as described above under "Stack Size Issues." 7. Build the NXWdigets Library Where /libnxwidgets $ cd /home/patacongo/projects/nuttx/nuttx/trunk/NxWidgets/libnxwidgets $ make TOPDIR=/home/patacongo/projects/nuttx/nuttx/trunk/nuttx 8. Build NuttX Where: nuttx directory $ cd /home/patacongo/projects/nuttx/nuttx/trunk/nuttx $ make ... 8. Run the "bringup" task: a. Start NuttX Where: nuttx directory ./nuttx NuttShell (NSH) NuttX-6.9 nsh> b. Execute NuttX Where: NSH command prompt NOTE that when you run NSH as a simulation, the commands are echoed twice -- once by Linux/Cygwin and once by NuttX: nsh> help help ... Builtin Apps: nx nxhello tc bringup nsh> bringup bringup bringup [2:128] c. Then do a kludgy thing Where: NSH command prompt The I/O with the Linux/Cygwin simulation is blocking. So while NSH is waiting for input nothing can run (see configs/sim/README.txt for more info). One way to make NSH stop asking for input is to sleep. nsh> sleep 10 sleep 10 NOTE 1: This is not a problem if CONFIG_SCHED_WAITPID is defined in the configuration file. If CONFIG_SCHED_WAITPID is defined, NSH will wait for the unit test to complete and it will not be necessary to sleep. NOTE 2: CONFIG_SCHED_WAITPID is defined in the sim/nsh2 configuration so you can probably ignore this kludgy thing. d. The Unit Test runs As soon as NSH sleeps, the unit test will run: bringup_main: Saying hello from the dynamically constructed instance CHelloWorld::HelloWorld: Hello, World!! bringup_main: Saying hello from the instance constructed on the stack CHelloWorld::HelloWorld: Hello, World!! bringup_main: Saying hello from the statically constructed instance CHelloWorld::HelloWorld: Hello, World!! 8. Debugging Where: nuttx directory In the simulation (only) you can use GDB or, better, the graphic front-end DDD to debug the code. Most embedded targets do not have good debugging capabilities. In order to debug, you have to have build with CONFIG_DEBUG_SYMBOLS=y. This setting is preselected in the sim/nsh2 configuration so that you don't have to do anything. Then under Linux or in a Cygwin X11 window, you can start the graphic debugger like: ddd nuttx &