Using Microchip MPLAB v5.70 with HI-TECH PICC, PICC Lite or PICC-18 compilers

If you are using an older version of the compiler, or for some reason you do not wish to update to v6.XX of MPLAB, then this guide is to help with integrating your HI-TECH compiler with v5.70 of MPLAB. Although the compilers are compatible with previous versions of MPLAB, it is recommended that you use v5.70 as it is the most up-to-date version prior to the release of MPLAB v6.xx.

Installation

Firstly, if you have not already done so, download v5.70 of MPLAB. MPLAB is freely available from Microchip's web site. To install, run the downloaded installer and follow the prompts.

Next, install the compiler also by running the installer and following the prompts. Refer to the compiler's quick start guide for specific details.

Special notes for installing v8.00 or higher of the compiler:

• Windows NT, 2000 and XP users should install the compiler while logged in with Administrator privileges.

• After installation, the compiler will run in demo mode and will expire in 21 days. In demo mode, some command line options are disabled, compilation is delayed. These are the only restrictions. You can still build projects, integrate with MPLAB, etc... in demo mode in the same way as the full release version. The demo mode restrictions can be removed if the compiler has been purchased and your details have been registered with us. Upon registration, you will receive your compiler's activation key via email.

• To activate your compiler after receiving a key, run the Compiler Activation program located in the compiler's installation directory. For help on compiler activation with PICC v8.02 or higher, click here.

Software integration

The default compiler options that are available with MPLAB are not quite complete and can cause problems in complex projects. You can update the compiler options in MPLAB by using one of the below updates:

For user's of HI-TECH PICC v8.00 or higher, PICC Lite and HI-TECH PICC-18 v8.12PL1 or higher:

• htmplab5.exe (35 KB)

If you are using an earlier version of the PICC or PICC-18 compiler:

• htmplab4.exe (90 KB)

Depending on which version of the compiler you are using, the compiler may configure MPLAB automatically during installation. Regardless of this, it is best to manually configure MPLAB so as to be certain everything is correct.

click to enlarge

To setup (or verify) the compiler's directory path is correct in MPLAB, click on the Project menu in the menu bar, and select Install Language Tool... This will open a new window, in which you can view the location of the Compiler, Linker and Assembler of the HI-TECH compiler that you have installed. If the directory shown differs from where your compiler is installed, you should correct this now. You might find it convenient to use the Browse facility to find your executable's location. The executable for ALL three tools (compiler/linker/assembler) will be PICC.EXE, PICL.EXE or PICC18.EXE (dependant on which compiler you are using).

Note that this should only need to be done once, unless you upgrade MPLAB or reinstall your compiler in a different directory.

In order for MPLAB v5.70 to display error/warning messages in its window, it requires the error/warning messages to be in the appropriate place (an error file) and in the format that it understands. The error/warning message format is configured by setting two environment variables as shown below:

• HTC_ERR_FORMAT=Error[000] %f %l : %s

• HTC_WARN_FORMAT=Warning[000] %f %l : %s

The method by which you set an environment variable differs depending on which version of Windows you are running. On the older Windows 95/98 it is done in an AUTOEXEC.BAT file. In Windows NT/2000/XP is can be done via the control panel. Refer to Microsoft's help for details about doing this with your version of Windows. FAQ #78 has more information about this.

In addition to having the messages in the correct format, they must appear in an error file. This is configured for each project you make and is described in the next section.

Creating a new project and setting compiler options

In MPLAB, click on the Project menu, and select New Project.... This will open a window called New Project. You need to give the project a name. Specify a directory for the project, and click OK. A new window will appear called Edit Project. From this window, you will need to specify which compiler you wish to use to build this project. Click Language Tool Suite... and select your HI-TECH compiler.

click to enlarge

click to enlarge

The bottom half of the Edit Project window allows you to add files to your project. By default it will already have the HEX file (named after your project) inserted. HEX files are produced by the link stage of the compiler. So it is necessary to configure this HEX file node to use the linker language tool. Click on Node Properties... The Node Properties window should now be showing. Make sure the Language Tool selection has the linker selected. Also choose Error File and set the error file name to be the same name as your HEX file, but with the extension .ERR. You can also select other linking options appropriate for your project at this point. When finished, click OK.

Having configured the HEX file node, you now may now add your .C and/or .AS files. This is done by clicking on the Add Node... button in the Edit Project window. In a similar fashion as configuring the HEX file, configure your C or AS file. For C files make sure the Language Tool is set to compiler and for AS files make sure it is set to assembler. Also make sure the error file is selected and the error file name is set to the name of the file you are configuring but with the .ERR extension. Repeat this step for each C or AS file you have or intend having.

click to enlarge

Special notes about compiler options:

• If you are using the MPLAB ICD, make sure you choose Compile for MPLAB ICD in the compiler options. This must be selected for ALL nodes of your project.

• If you want to use 32-bit floating point numbers, make sure you choose Floating point for doubles: 32-bit in the compiler options for ALL nodes of your project. Be consistent in selecting 32-bit doubles, do not select 24-bit for one file and 32-bit for another.

• Be careful when selecting your build options as some of the options offered will guarentee MPLAB reporting a build failure. The reason for this is that some options do not follow though to the link stage. So unless it is your explicit intention to do so, DO NOT select any of these options:

  -S (compile to assembly only),
  -PROTO (generate function prototypes)
  -PRE (generate preprocessed source)

• When configuring the compiler options it can be very useful (for debugging purposes) to generate an assembler list file and a map file. Assembler list files contain a mixture of your original C source code and the generated assembler code. Map files contain all information about how your code has been positioned in memory. Map files also contain a call graph which shows your stack usage.

• If you are having problems with your program fitting into the available ROM/FLASH space, don't forget to turn on the compiler's optimizations. Compiler optimizations will attempt to reduce your program's code requirements without effecting the way it operates. There are two types of optimizations: global optimizations and assembler optimizations. To enable these, select them in the compiler options for each file of your project.

Building a project

Now that your project has all of its files and your build options have been set up, it is now ready to be built.

Simply click on MPLAB's Build All button to begin the project build. MPLAB should open a new window called Build Results which will either contain a memory summary or a list of errors. If you get a memory summary, well done. Otherwise, you can double click the error message, MPLAB will open the source file and indicate which line is in error.

click to enlarge

Debugging your code

If your program builds successfully, the compiler should generate a HEX file and a COD file. The COD file contains all the information necessary for high-level debugging. You may notice that some complex types are not able to be viewed in the watch window. This is a limitation of the COD file format and MPLAB. Microchip have improved this in MPLAB v6.XX (via the use of COF files) and if you require better debugging, it is recommended that you update to it.