diff options
Diffstat (limited to 'apps/FaCE/README')
| -rw-r--r-- | apps/FaCE/README | 287 |
1 files changed, 0 insertions, 287 deletions
diff --git a/apps/FaCE/README b/apps/FaCE/README deleted file mode 100644 index a4bd2d981b1..00000000000 --- a/apps/FaCE/README +++ /dev/null @@ -1,287 +0,0 @@ -=== -=== 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. |