From 4dedf494c242b2c4b52707441eefe2a36fbacf0f Mon Sep 17 00:00:00 2001 From: patacongo Date: Thu, 22 Mar 2012 21:22:59 +0000 Subject: First check-in of NxWidgets git-svn-id: svn://svn.code.sf.net/p/nuttx/code/trunk@4505 42af7a65-404d-4744-a932-0658087f49c3 --- NxWidgets/UnitTests/README.txt | 394 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 394 insertions(+) create mode 100644 NxWidgets/UnitTests/README.txt (limited to 'NxWidgets/UnitTests/README.txt') diff --git a/NxWidgets/UnitTests/README.txt b/NxWidgets/UnitTests/README.txt new file mode 100644 index 000000000..b0f3c9aab --- /dev/null +++ b/NxWidgets/UnitTests/README.txt @@ -0,0 +1,394 @@ +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) Other Possible nuttx/.config changes + e) Other Possible apps/.config 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). + + 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. + + 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) Other nuttx/.config 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. + + e) Other apps/.config changes -- NON-NSH configurations only. + + For non-NSH configurations (such as the sim/touchscreen) you will have to + remove the CONFIGURED_APPS seting that contains the user_start function so + that you use the user_start in the unit test code instead. So, for example, + with the sim/touchscreen configuration you need to remove the following from + the apps/.config file: + + CONFIGURED_APPS += examples/ ## REMOVE + + 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: + + CONFIGURED_APPS += examples/nsh ## DO NOT REMOVE + + Then DO NOT REMOVE the CONFIGURED_APPS setting. Go back and re-read c) + above. Do either c) or d). Don't do both! + + sim/nsh2 and stm3210e-eval/nsh2 both NSH configurations. You do not need + to change anything further in the apps/.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 /trunk/UnitTests/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 /trunk/NXWidgets/libnxwidgets + make TOPDIR= + +6. Build NuttX including the unit test and the NXWidget 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 + +Example +======= + +1. Configure sim/nsh2 + Where: nuttx and nuttx/tools directory + + $ cd tools/ + $ ./configure.sh sim/nsh2 + $ cd - + +2. Edit nuttx/.config to enable C++ support + + Do nothing... sim/nsh2 already has C++ support enabled. + +3. Install the CButton C++ application (for example) + Where: NXWidgets/trunk/UnitTests/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/gui/raztek-nxwidgets/trunk/UnitTests/tools/../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 XWidgets/trunk/NXWidgets/libnxwidgets + + $ cd /home/patacongo/projects/nuttx/gui/raztek-nxwidgets/trunkXWidgets/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 & -- cgit v1.2.3