diff options
Diffstat (limited to 'ACE/contrib/FaCE/README')
| -rw-r--r-- | ACE/contrib/FaCE/README | 289 |
1 files changed, 289 insertions, 0 deletions
diff --git a/ACE/contrib/FaCE/README b/ACE/contrib/FaCE/README new file mode 100644 index 00000000000..c8a4713758c --- /dev/null +++ b/ACE/contrib/FaCE/README @@ -0,0 +1,289 @@ +$Id$ + +=== +=== FaCE (Front-end for ACE CE) +=== +=== Object Computing, Inc. <http://www.ociweb.com> +=== St. Louis, Missouri +=== Copyright (C) 2002. All rights reserved. +=== +=== V1.01, March 30th, 2002 +=== + + +== What's FaCE? + +FaCE is a simple front-end framework for testing and debugging non-Windows +CE applications on the Pocket PC 2002 platform. Originally, FaCE was +developed to test ACE and TAO components internally in Object Computing, Inc. +However, since it has shown dramatic increase of productivity in a lot +shorter amount of time, it has been prepared as a package for all programmers +who want to test and run existing codes (non-WinCE native codes) on Pocket PC +2002 and WinCE 3.0. + +The features of FaCE are: + + 1. command line parameter support + 2. command line history support (never type in same command line again) + 3. output displayed on the windows screen + 4. output to file (with append and overwrite support) + 5. does not use MFC + 6. almost no modification to existing user code + 7. easy to enable and disable after install + +* Default project files only contain Pocket PC 2002 platform configuration. + A new configuration can be added for other WinCE 3.0 platform from eVC. + + +== Package Contents + +Files contained in FaCE package are: + + Main Framework Files for both ACE users and non-ACE users + - ACE_Racer.bmp + - FaCE.h & cpp + - FaCE.ico + - FaCE.rc + - newres.h + - resource.h + - TAO.bmp + + ACE entry point definition file + - FaCE_OS.h + + Additional Framework files for non-ACE users + - CE_ARGV.h & cpp + - CE_Screen_Output.h & cpp + + Files for loading skeleton FaCE from eVC + - FaCE.vcp & vcw : FaCE Project files for ACE users + - FaCENOACE.vcp & vcw : FaCE Project files for non-ACE users + - Main.cpp : almost empty entry point function + + Misc. Files + - ACE.ico : a bonus icon of ACE logo + - License.txt : license and warranty information + - ReadMe.txt : this document + + +== Requirement + + - Microsoft(C) eMbedded Visual Studio/C++ (eVC) 3.0 + - Pocket PC 2002 SDK + + ** For ACE-users only: + - ACE+TAO installed and configured for WinCE build only for ACE-users + - ace and ace_os libraries built for WinCE and loaded on machine + + +== Important Note + +It has been reported that certain Pocket PC 2002 machines with ARM processor +can be totally dead and will not even respond to the hard reset. While the +real cause of this problem is unknown, HP has released a patch for this +problem. We have tested it, and it seems working fine on our machine (HP +Jornada 568), which is our 5th machine that has been running fine for the +longest time. + +As this has been identified by hardware manufacturer and can be fixed as HP +did, Object Computing, Inc. (OCI) or any member of ACE+TAO community cannot +be responsible for this problem. If this problem happens during debugging, +contact your hardware manufacturer for fix or replacement. It has found +that almost all Pocket PC 2002 machines regardless of manufacturers have same +problem. + +Also, Phil Mesnier at OCI has found that virtual function calls under certain +situation can cause a problem that randomly changes parameter and pointer +values over function calls. This is due to the incorrect instructions +generated by eVC for ARM processor. So far, no solution or patch has been +released by compiler vendor, although vendor is aware of this problem. + +Since Pocket PC 2002 is based on WinCE 3.0, ACE+TAO as well as FaCE should +be able to run on any WinCE 3.0 platform by adding a new configuraion with +minimal change. + + +== Installation & Setup + +1. Create a subdirectory named 'FaCE' (or anything in your taste) under + your current project directory. + +2. Copy FaCE_OS.h to the ACE_ROOT/ace directory, and add following line at + the end of your ACE_ROOT/ace/config.h file: + + #include "FaCE_OS.h" + +3. Copy main framework files listed above and add them into "your" project + (NOT FaCE.vcw/vcp). For non-ACE users, copy additional framework files + for non-ACE users in addition to the main framework files. + It would be a good idea to create a new folder in your project and put + all FaCE files into it. This way, it will be easy to disable FaCE by + setting the folder excluded from the build on the folder property option. + + ** IMPORTANT! ** + FaCE does NOT use MFC. Thus, if your project is already set for + 'Not using MFC', then do not change the setting. + + * Note: Make sure those files are not shared by multiple executables. + Each project must have its own copy of those files. + It is a good idea to create a separate folder on your project + and put FaCE related files into that folder. In that case, + if you want to disable FaCE and run by using normal 'main', + then you can simply set the whole FaCE folder excluded from + build in the project setting menu. + +4. Change your 'main()' function part similar to the following example. + + #ifdef ACE_HAS_WINCE + #include "FaCE/FaCE.h" // use the name of subdirectory you created + int FaCE_MAIN (int argc, ACE_TCHAR *argv[]) + #else + int ACE_TMAIN (int argc, ACE_TCHAR *argv[]) // ACE normal entry point + #endif + + Change the directory name for "FaCE/FaCE.h" if necessary. + For non-ACE users, use 'UNDER_CE' instead of 'ACE_HAS_WINCE'. + + == Possible Additional Change + + Above change will be the only change if your program compiles and links + fine under eVC. It does not mean that your program is WinCE-ready but + just means that your program does not include the libraries that are not + supported by WinCE, such as iostream. + + For ACE users, good examples will be the ACE test programs under + $ACE_ROOT/test. + + For non-ACE users, I highly recommend to create a project for WinCE first + if it has not already been done and write your code using wmain. + Try compile and link your program without FaCE to check your program does + not include any libraries not supported by WinCE. FaCE supports text output + by aliasing 'cout' in FaCE.h; however, it is NOT a real iostream but an alias + for CE_Screen_Output class. You may need to use '#ifdef UNDER_CE' for your + iostream includes, if you want to share the code among different platforms. + + Also, it is important to match the parameter types for 'wmain' function. + For WinCE, it MUST be in the format of: + + int FaCE_MAIN (int, wchar_t**) + + and you can leave your original wmain type as it was for non-CE platform + definition. + +5. Go to 'ResourceView' or double-click on the 'FaCE.rc'. Open 'String Table -> + String Table' from the resource browse view, and change the string value (caption) + defined for 'IDS_APP_TITLE' from 'FaCE' to your program name. This will + help identifying multiple FaCE-fied applications when you brose them + through system memory -> running programs in case of crash. + +6. That's it! + +** Optionally, you can personalize the icons defined for FaCE for your own. + To do this easily, load "FaCE.vcw" (requires ACE library) or "FaCENOACE.vcw" + from eVC. Also, FaCENOACE.vcw can be used as 'hello world'-type starting + frame-work for non-WinCE programmers. + +** Non-ACE users may see the warning messages saying, "Could not find the file xxx", + for ace.h, Log_Msg.h, OS.h, and CE_Screen_Output.h. This is due to the eVC's + not-so-perfect precompilation file checking and totally harmless. + +** Later if you don't want to use FaCE anymore, simply restore your original + main function and remove FaCE files from your project (or exclude FaCE files + from build). ACE library does not have to be rebuilt as FaCE_OS.h only + contains macro. + +== Running FaCE + +1. Command line option + +User can specify the command line option for the program by using 'Settings -> +Command Line' from the FaCE menu. FaCE will automatically save all user-entered +command line parameters as a ASCII format file named 'Parameters.txt' in the +root directory of WinCE device/emulator. User can edit and change by openning +this file from any text editor and save as a ASCII text file with DOS standard +CR/LF combo. This will greatly save time especially when you are working on the +Pocket PC machine that does not have keyboard. Remember NOT to convert file +format to Unicode; it must be standard DOS ASCII text file. + +2. Output Saving + +You can save output to file by selecting 'Tools -> Save To File'. By default, +FaCE will not create/save any file. Also, any output received before setting +up this feature will not be saved. + +If the file with specified name exists, FaCE will ask whether you want to +append to the end of file or erase and overwrite. All output files will be +saved in the root directory of the system. + +3. Running Your Program + +'Setting -> Run' will execute your program. Two tags, 'START' and 'END' +indicate the beginning and end of your code. + +For ACE users, any log message sent to ACE message log (ACE_DEBUG, for example) +will be displayed on the screen. Also, if you have setup to save to file, +the same contents will be saved to the file as well. Note that the output will +NOT have ACE internal tags (i.e. Dec 04 14:51:12.000 2001@LM_DEBUG@) because +FaCE uses callback message function, and ACE does not pass those tags along +with the output message. + +For non-ACE users, you can declare your own local copy of CE_Screen_Output +object. For example, you can declare CE_Screen_Output object in your cpp file +like: + + CE_Screen_Output cout; + +and use it like, + + int a = 100; + wchar_t* strTemp = L"Hello, world!"; + cout << L"String : " << strTemp << L"a = " << a << endl; + +Remember, CE_Screen_Output is just a simple text output function and does not +have the full capabilities of iostream, which is not available for WinCE 3.0. + +4. In case of crash + +If you have started your code, but the code crashes, which can be easily +identified by looking for the 'END' tag, then you can use Windows CE's memory +program to kill the process (Start -> Settings -> System tag -> Memory -> +Running Programs tag). If you have changed IDS_APP_TITLE in the resource +viewer, then you will see the name you have specified; otherwise, FaCE will be +listed. You can select the name and stop the process by clicking 'Stop' button. +Sometimes, you may need to reset the machine if you cannot access memory program. + + +== Note + +- This FaCE framework does not use any MFC; it only uses general Win32 + API, thus, your project setting does not have to be changed. + +- FaCE is for the 'legacy' Unix/DOS style console applications that + do not use any Win32 and MFC for Windows OS. Programs that are already + using native Windows/WinCE API's will not need FaCE framework. + +- If you run your application from FaCE (Settings -> Run), 'START' and + 'END' will appear at the beginning and end of output messages from your + application. If you see 'END' lable after execution, you can run your + program again without exit and start up FaCE again. + +- Make sure to terminate FaCE by selecting 'Settings -> Exit'. It will + completely terminate FaCE session; Clicking on the 'X' button + at the top-left corner of the screen will not, just like most WinCE programs. + +- FaCE_MAIN is only for the WinCE port of ACE, ensuring proper windows system + message filtering along with proper registraion so that user can see the + process from memory setting and task switcher applications. + +- ACE and FaCE do not overrides native WinMain. If you are developing for + Windows OS only, your WinMain should be just safe from any overrides. + In this case, of course, you don't need to use FaCE package. + + +== Question or Comment + +If you have question and/or comment specific to the FaCE, please contact +Si Park at spark@ociweb.com or Justin Michel at michel_j@ociweb.com. + +For general ACE+TAO support, please refer to comp.soft-sys.ace or contact +Object Computing, Inc. at http://www.ociweb.com. |