ProKylix 1.2    Copyright 2001 by Helmuth J. H. Adolph

Freeware and Professional Mode

---------------------------  Installing ProKylix  ----------------------------

A  General
----------

 1. Check your CPU:

    ProKylix 1.x runs on Pentium and Pentium compatible CPU's. It has been
    tested on:
    - Pentium Overdrive 120 MHz, Intel Celeron 400 MHz and Intel Pentium II
      with 400 MHz.
    - AMD K6 166 and 233 MHz, AMD K6-2 266 and 300 MHz, AMD K6-3 400 MHz,
      AMD Athlon 600 MHz,


    It definitely does NOT run on a Cyrix 6x86. The Cyrix M2 and IDT have
    not been tested.

 2. If you have already an older version of ProKylix, you MUST delete these
    old files first: Profadjx.dcu, Profcbrx.dcu, Profintx.pas, Profonlix.pas
    and Profonli.xfm. If you have used the Setup program for installation
    and left the files where they have been installed, this is done
    automatically.

 3. Install ProKylix either automatically or manually (see ReadmeXX.pdf).
    Automatic installation is done this way:

    - Login as the same user as that you used when installing Kylix,
    - IMPORTANT: End Kylix before installation, otherwise ProKylix is not
                 integrated into the tools menu.
    - Start a shell,
    - Set the current directory to that directory, where the unpacked files
      of ProKylix are stored (cd /.....),
    - Enter sh startsetup kylixpath
      (example for kylixpath: /home/username/kylix)
      It takes same time until you see the program Setupx appear because
      Setupx searches the Kylix installation directory,
    - Accept the license conditions,
    - Check the version of Kylix which you want to install ProKylix for
      (currently only one version) and
    - Click the Start button.
    After this procedure you can start ProKylix from the Kylix tools menu
    or by a shell: sh startprofiler.

4. You should read the documentation (ReadmeXX.pdf), Post-Mortem-review is only
    described in the documention.


B.  Testing the installation with the example programs (for automatic setup)
----------------------------------------------------------------------------

  If you have installed ProKylix with Setupx, you can now, for testing
  the installation or for checking the accuracy of ProKylix, compile the
  two example programs installed in the subdirctories under your installation
  directory. The example in the directory DONT-PROFILE should not be
  profiled, only compiled. It has a built-in runtime measurement and gives
  you the runtime for some typical code constructions you would always come
  across when you write programs yourself.

  ! The compiler switch for optimization should be unchecked !

  The program in the directory PROFILE-ME is, in principal, the same program
  without the built-in runtime measurement. You should first compile this
  program (with optimzation unchecked) and then start ProKylix from the
  Tools-menu of Kylix. Select Profile', select this program, check the box
  'Autostart' and then click the Run-button. After that define the compiler
  symbol 'PROFILE' in Kylix and compile it again.

  Start the program, press the start button and then close the application.
  In ProKylix select the function 'View', the result file ptmainx2.txt should
  be selected already, and click Run. A window should appear with the
  measurement results. Keep this window open.

  Compile the program in the directory DONT-PROFILE and start it. Compare
  the results for runtime measurement of both programs, they should be
  nearly identical (differences depend on the cache size of your CPU - see
  progrm description.


C. Profiling your own sources
-----------------------------

 1. Save all your sources (e.g. zip them into an achive file).

 2. Compile your program.

    If no errors occur:

    3. Start ProKylix

    4. Select Profile and mark the correct Kylix-version. If you use
       conditional symbols, you should  see them in your ProKylix window (if
       not, you haven't saved your project).

    5. Select your dpr-file as project.

    6. Click on Run.

    7. Define the compiler symbol PROFILE in the compiler options (conditional
       definitions), NOT in the source file! Uncheck the
       Optimization-option !!!!!!! and make a COMPLETE compilation.

    8. Start your program and let it do what it has to do.

       Attention: When you start your program, it takes a second or two for
                  calibration (estimation of your CPU speed and measurement
                  correction times).

                  Please do not start any other programs while calibrating,
                  otherwise the results are incorrect.

                  After the calibration phase the Online operation window and
                  your form(s) is/are shown.


    9. After your program has terminated, start ProKylix, select VIEW,
       select the result file of your program if not automatically done.
       The name of the result file is 'programname.txt'. Then click Run.
       After these actions the viewer window opens and you can look at the
       results of the measurement.

       If, at profilation time, you have checked ASCII-output file you also
       can have a look into the result file (programname.ben) with Kylix
       or print it with Kylix (use landscape format).

   10. Checked procedures might use a few CPU-cycles more than they would
       use without measurement. The reason is, that the measurement procedures
       in the unit Profcbrx.dcu are moved into the memory cache and delete
       those procedures that would be there without measurement. Depending
       on the CPU you use, the results are very accurate or less accurate.

       The L1-cache of the plain pentium has 16 kB,
       the L1-cache of pentium MMX / PII or Celeron have 32 kB Cache size,
       the AMD K6 / K6-2 / K6-3 have 64 kB L1-Cache Size.
       Also the L2-Cache sizes differ, the processor might have a L3-cache
       (e.g. the AMD K6-3). Also the accesses to L2-cache differ (1/3, 1/2,
       1/1 CPU frequency or bus frequency).

       That's why the results on an AMD K6 are more excact than on pentium
       processors.


11. See the readmexx.pdf file for further instruction or information.

12. Limitations of use:

    Console applications can not have an online operation window.
    For further minor important limitations see readmexx.pdf.

--------------------------  Uninstalling ProKylix ----------------------------

Delete the files, directories and links you have created. For that you can use
the Setup Program.


-----------------------  ProDelphi Distribution Files  ------------------------

  startprofiler  Startscript for ProKylix (sh startprofiler)
  Profiler       ProKylix executable file
  Profintx.dcu   The profiler interface with the measurement procedures.
  Profcbrx.dcu   The calibration procedures for an exact measurement.
  Profadxj.dcu   Supplies the calibartion procedures with necessary 
                 information.
  Profini.dcu    Reading Ini-files for ProKylix.
  Profonlix.pas  The online operation window for ProKylix.
  Profonlix.xfm  The form of the online operation window.
  readmexx.pdf   Description of ProKylix x.x (Acrobat reader-Format)
  order.txt      Information on how to order the registered version
  license.txt    License Agreement / Warranty Disclaimer
  install.txt    This file.
  news.txt       News and Hints for usage of ProKylix.
  Setupx         Program for automatic setup.
  startsetup     Shell-script for starting the setup program
                 (sh startsetup kylixpath), where kylixpath e.g. could
                 be /home/user/kylix)
  Getspeed       Used for emulation of other PC's (currently not supported)


-------------------------  Files created by ProKylix -------------------------

proflst.asc    Contains information about the procedures to be measured for
               profiling or traced for post mortem review.

profile.ini    Options for time measurement, screen coordinates for the
               online operation window.

----------  Files created at runtime by measured or traced programs -----------

progname       progname is the name of your executable, created by Kylix.

progname.txt   Results in data base format (runtimes of the procedures), used
               by the built-in viewer.

progname.tx2   Run numbers, CPU-clock-rate and headlines for the built-in
               viewer.

progname.nev   Contains the names of those methods that are not called at
               time of measurement.

progname.hst   History file, stored by the viewer when the history button
               is pressed. Contains runtimes for later comparison after
               optimization.

progname.ben   Results of the time measurement in ASCII if the option
               ASCII-output file was checked at profiling time.

progname.swo   List of procedures that have to be deactivated for time
               measurement at next program start.

progname.pmr   Call stack in case of a trapped exception (for Post Mortem
               Review only).

All files are created in the output directory for the exeecutable.

