path: root/contrib/FaCE/README

===
=== 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.