
INSTALLATION OF CC5X


SYSTEM REQUIREMENTS
-------------------

The CC5X compiler is available as a 16 or 32 bit application (DOS16/
WIN32) and runs on IBM-PC compatible machines using MSDOS or
Windows (95/98/me/NT/2000).



INSTALLATION
------------

First create a directory/folder on the hard disk where the compiler
files should be located. Then copy all CC5X files to this directory.

CC5X is now ready to compile C files. Header and C source files have
to be edited by a separate editor (not included), for instance in
MPLAB.

If you are mainly working in a MSDOS window, it may be useful to
modify PATH in the AUTOEXEC.BAT file to allow the operating system
to find the compiler from any directory (PATH ...;C:\CC5X;...). This
is not a required step.

The CC5X files can be deleted without any uninstallation procedure.



SUPPORT FOR LONG FILE NAMES
---------------------------

CC5X supports long file names. Currently, it is not possible to use
spaces in file names or in directory names. The truncated short
format must then be used.

The truncated form is decided by the file system according to some
rules. The best guess consists of the 6 first characters of the long
name plus ~1. The last number is different (~2) if the first 6
characters are equal to another name in the same directory.

If the path should be:  "C:\Program Files\MPLAB\longfilename"
the equivalent short format is often:  C:\PROGRA~1\MPLAB\LONGFI~1

The name "C file" becomes CFILE~1 because spaces must be removed.

MPLAB uses and display the short format only. The short format name
can be found when using Open File and point-and-click to move along
a particular path.




USER INTERFACE
--------------

The CC5X compiler is a command-line program. It requires a list of
command line options to compile a C source file and produce the
required files.

Starting CC5X from Windows can be done from the Start->Run menu.
Then type the full path name including cc5x.exe (or use Browse). The
list of compiler command line options are then written to the
screen. The normal way of using CC5X is to use it as a tool from an
integrate environment like MPLAB.

In a MSDOS window, the compiler is invoked by writing:

  cc5x

This produces an list of the valid arguments to the compiler.

Compiling a program is done by:

  cc5x sample1.c

Generating an assembly file:

  cc5x -a test.c



MPLAB INSTALLATION (VERSION 5)
------------------------------

The CC5X compiler can be used inside the MPLAB environment. Note
that CC5X can only run in command-line mode.

Installing CC5X in MPLAB:

1. First install CC5X on your computer as described initially.

2. Then copy the files CC5X.MTC and TLCC5X.INI from the CC5X folder
   (directory) to the MPLAB folder (this folder contains other .ini
   and .mtc files).

3. Next time MPLAB is started, select the Project->Install Language
   Tool menu item. Select CC5X from the Language Suite. Then the
   Tool Name (C-Compiler). Then the right Executable (c:\cc5x\cc5x.exe
   or similar). Note that the Browse button can be used to find the
   executable. Also mark the Command-line box. Then click OK. CC5X
   will then be one of the selectable tools in MPLAB.

The following is a brief description on how to use CC5X on a new
project under MPLAB. Please refer to the help information available
under MPLAB for a complete description.

1. Start MPLAB and create a new project (Project->New Project).
   Chose a project name (*.prj) and a directory where to locate this
   file and the other project files (C,H,HEX,ASM). Type <Enter> or
   the OK button.

2. Edit Project is the next window. MPLAB suggests a Target Filename
   based on the project name. This is automatically changed during
   step 4. Include Path do not have to be specified (and should be
   left open initially). Library Path and Linker Script Path are not
   used anyway. Use Development Mode to select the processor and
   simulator/debugger (ignore any MPLAB warning at the current
   stage). Change Language Tool Suite to CC5X (this is one of the
   menu items if the installation steps was completed).

3. Double-click on the (target) name in the Project Files box. A
   window named Node Properties pops up. The typical command line
   options for CC5X are already marked. Options are disabled or
   enabled by clicking on the box (second column) after the option
   name. Note that the right Include Path (c:\cc5x) is required to
   make CC5X find the header files. Click the OK button.

   NOTE: It is not enough to select the right processor in MPLAB
   alone. CC5X also need to know the processor type, either through
   a command line option (-p16C74) or by a pragma statement in the
   beginning of the program (#pragma chip PIC16C74).

4. Click on the Add Node button. Type the name of your main C file
   or chose an existing C file (sample1.c). It is recommended to try
   one of the supplied example files initially. If the (sample) C
   file does not reside in the selected project directory, copy it
   to this directory first. Note that files included in the main C
   file (and nested include) must not be listed in the Project Files
   box. Click the OK button.

5. Open the main C file (File->Open or Ctrl-O). Compile the file
   using Project->Make Project (or F10). Note that Project->Build
   Node (Alt-F10) requires that the main C file is in the current
   active window. Double-click on the error messages (if any) and
   correct the C code. Repeat the compilation until there are no
   error messages.

   NOTE: If MPLAB says 'Build Failed' and there are no error
   messages generated by the compiler, please go to main paragraph
   'TROUBLESHOOTING' in this file.

   Use File->Open to inspect the generated files. The *.occ file
   contains compiler output information.

   IMPORTANT: If you selected the Error File command line option,
   then MPLAB will suppress the output from the compiler and display
   the content of the *.err file only. Change this option to your
   preferred setting. It may also be necessary to change some of the
   command line options (Processor, Hex Format) if MPLAB pops up a
   warning window.

6. CC5X allows simulation in C or assembly mode using the COD file.
   This is one of the compiler options: Debugging mode (C) or (ASM).
   Change the compiler options setting by selecting the Project->
   Edit project menu item. Double-click on the (target) file in the
   Project Files. Click OK. If you need many command line options,
   please read main paragraph 'USING OPTIONS ON A FILE' in this file.

7. Options->Development Mode can be used to set/change the debugging
   tool (MPLAB-SIM Simulator, SIMICE, Emulator, etc.). You are then
   ready to trace program execution.

8. Watching variable contents during tracing:
   MPLAB allows Watch windows containing variables to be defined.
   Select Window->Watch Windows->New Watch Window. Select the
   variable name. Select Properties. Select the right size (8,16,24,
   32 bit). Select the Low:High byte order if the variable size if
   more than 8 bit. Select the desired format (Hex,Decimal,
   ASCII,..). It is possible to watch the same variable using
   different formats. Close the Add Watch Symbol window when
   finished. The INS key can be used to add a new symbol to the
   current active Watch window.

   Bit variables: it is recommended to first define a char variable
   and use an overlay definition to define the bit.
       char cx;
       bit bx @ cx;
   This simplifies watching the bit value.




TROUBLESHOOTING
---------------

Problem A: MPLAB says 'Build Failed' and there are no error messages
           generated by the compiler.

   i) One cause is that CC5X was not started.
      This can happen if the installation was not successful.

      Cure: Select the Project->Install Language Tool menu item. Use
      the Browse button to find the executable (cc5x.exe). Then
      click OK.

   ii) MPLAB may fail to compile if the command line including
       options that starts cc5x is too long (around 148 characters
       seems to be critical). This can happen if long path names are
       used (for the include directory and/or the executable).

      Cure: remove most command line options found in
      Project->Edit Project..(target)..Node Properties.
      This window tells which command line options are used. Click
      OK. Then try to compile (using F10). It may be required to put
      the command line options on a separate file to avoid this
      problem (check next paragraph).

      If compilation still fails, please count the number of
      characters in the command line generated by MPLAB (Build
      Results). If this command line which starts cc5x contains more
      than 147 characters, please remove more options. It may even
      be necessary to move the folders used closer to the root to
      avoid very long path names. It should be easy to detect the
      path names that are very long.


Problem B: Project Build (F10) in MPLAB produces an empty window.

   Cure: Same as Problem A, point ii).


Generally, it is recommended to use one of the supplied examples
initially. Also FEW command line options until a successful
compilation is found.



USING OPTIONS ON A FILE
-----------------------

ALL compiler options can be put on a file. Just separate them with a space
or a new line. Also check the supplied file op.inc for details.

The options that reside on a file should be disabled in MPLAB.
Select Project->Edit Project..(target)..Node Properties,
and disable the options. Also, under additional command line options,
add +op.inc (or the filename that you chose including optional pathname).

The pathname to the option file can be omitted if the option file in put in
the same folder as the other project files.

You can use several option files, one for common options, and one
for each project (which use include on the common option file).

