Multiple Compilation Unit Example

Files in project:
main_mcu.c Primary file for the first compilation unit
filter_mcu.c Primary file for the second compilation unit
report_mcu.c Primary file for the third compilation unit
project_mcu.h Include file with project wide definitions, should be included by all units
filter_mcu.h External definitions for filter, should be included by all units that use the
filter unit
report_mcu.h External definitions for report, should be included by all units that use
report
buildall_mcu.bat Batch file that compiles and links all units
build_mcu.bat Batch file that recompiles files needing compiling and links
project_mcu.pjt Used by build_mcu.bat to list project units

main filter report

#include's: #include's: #include's:
project_mcu.h project_mcu.h project_mcu.h
filter_mcu.h report_mcu.h
report_mcu.h

Definitions: Public Public Definitions:

main() program Definitions:
clear_data() report_line_number
filter_data() report_data_line()
Uses: report_error()
clear_data() Uses:
filter_data() report_error()

report_data_line()
report_line_number

Each unit:
*.o (relocatable object)
*.err (error file) project_mcu.hex (final load image)
*.osym (unit symbols) project_mcu.lst (C and ASM listing)
project_mcu.sym (project symbols)
project_mcu.cof (debugger file)
Building the project from the command line:

1. Move the project files into a directory.

2. Edit the buildall_mcu.bat file and make sure the path to CCSC.EXE is correct.
3. From a DOS prompt set the default directory to the project directory.
4. Enter: BUILDALL_MCU

"c:\program files\picc\ccsc" +FM +EXPORT report_mcu.c

"c:\program files\picc\ccsc" +FM +EXPORT filter_mcu.c
"c:\program files\picc\ccsc" +FM +EXPORT main_mcu.c
"c:\program files\picc\ccsc" +FM
LINK="project_mcu.hex=report_mcu.o,filter_mcu.o,main_mcu.o"

Automatically building by recompiling needed files:

1. The required lines in the project_mcu.pjt file are:

[Units]
Count=3
1=filter_mcu.o
2=report_mcu.o
3=main_mcu.o
Link=1
2. From a DOS prompt set the default directory to the project directory.
3. Enter: BUILD_MCU

Note that after a project is linked if no .pjt file exists the linker will create
one that may be used with the BUILD= option in the future.

"c:\program files\picc\ccsc" +FM BUILD=project_mcu.pjt

Replacing the linker command line with a linker script:

1. Create a file named project_mcu.c with the following lines:

#import( report_mcu.o )
#import( filter_mcu.o )
#import( main_mcu.o )
2. Compile each unit (report_mcu, filter_mcu, main_mcu).
3. Compile project_mcu.c
Using the CCS PCW IDE to work with multiple compilation units:

● The above screen is from OPTIONS > PROJECT OPTIONS after loading the
project_mcu.pjt file. If the file does not exist create the project manually and
make a screen like the above.

● To create a new project select “File -> New ->

Create Project”

● Then select the main file to be used for the

project. In this case it would be “project_mcu.c”
from the example files

● In the dialog box select the “Multiple

Compilation Units” check box. This will allow
multiple source files to be added.

● Select “Add File” and add the files that will be

used in the project and click apply. In this
example they would be “report_mcu.c”,
“main_mcu.c” and “filter_mcu.c”

● The pane to the left is the FILES slide out that

is available from VIEW > FILES under the
“Windows” section. At this point, only the “.c”
files that were added will be listed under the unit names.
● Right click on a unit name (like filter_mcu) and select COMPILE to compile just
that unit. Compiling a specific unit brings in the other files that are needed to
complete that unit. In this case the files brought in are the “.h” files that were
included in the example code.

● Right Click in the FILES slide out and select BUILD ALL to rebuild and link the
whole project. Performing a BUILD ALL creates all the “.h” files that get linked to
the units and it also links the units together to create the output files that are
loaded onto the devices. Once a BUILD ALL is completed with no errors, the
code is ready to be run.

● This pane is helpful in managing each unit in the project. Review the right click
options for the full range of options.
Using MPLAB X IDE to work with Multiple Compilation Units

● Create a new project by selecting “File -> New Project” from the toolbar. Follow the
dialog boxes to specify the project type.

● Make sure MPLAB is configured for the proper chip, as the CCS C compiler uses this
selection to determine which compiler to use (PCB, PCM, PCH, PCD, etc). The chip is
selected when creating a new project in the “Select Device” window.

● Selected the ICD3 tool to be used for connecting.

● Select to use the CCS C Compiler.

● Specify the project name and directory

● Add source files by either a.) right clicking on 'Source

Files' in the MPLAB Project window or b.) selecting
“File -> New File..” from the MPLAB toolbar and
following the dialog box.

● Performing a “Run -> Build Project” will compile the

source files separately, and link the .o files in the final
step.

● An individual unit can be compiled by right clicking on

the file in the MPLAB Project window and choosing
'Compile.' This will not re-link the project when it is
done compiling this unit.

● An already compiled .o file can be added to the project,

and will be linked during the Make/Build process.
MPLAB Project window
● If there is only one source in the project, it will be
compiled and linked in one phase (no .o file will be created).

● Many project build options (such as output directory, include directories, output files
generated, etc) can be changed by selecting “Run -> Set Project Configuration“ from
the MPLAB toolbar.

● If the compile fails with an error that says something like “Target chip not supported” or
“Compiler not found” make sure that a.) you have the proper PIC selected (use “Run ->
Set Project Configuration -> Conf:” from the MPLAB toolbar), b.) the CCS C Toolsuite
has been selected for this project (use “Run -> Set Project Configuration -> Conf:”
under “Compiler Toolchain” from the MPLAB toolbar) and c.) the path for CCSC.EXE is
configured correctly for your installation of the CCS C Compiler (use “Tools-> Options
-> Embedded -> Build Tools” on the MPLAB toolbar)
 Notes

● By default variables declared at the unit level (outside a function) are visible to all other
units. To make a variable private to the unit use the keyword static. Notice
report_mcu.c defines the variable report_line_number. If the definition were changed
to look as the following line then there would be a link time error since main_mcu.c
attempts to use the variable.
static long report_line_number;

● This same rule applies to functions. Use static to make a function local to the unit.

● Should two units have a function or unit level variable with the same name an error is
generated unless one of the following is true:
● The identifier is qualified with static.
● The argument list is different and two instances of the function can co-exist in
the project in accordance with the normal overload rules.
● The contents of the functions are absolutely identical. In this case the CCS
linker simply deletes the duplicate function.

● The standard C libraries (like stdlib.h) are supplied with source code in the .h file.
Because of the above rule these files may be #include'd in multiple units without taking
up extra ROM and with no need to include these in the link command since they are
not units.

● #define's are never exported to other units. If a #define needs to be shared between
units put them in an include file that is #include'd by both units. Project wide defines in
our example could go into project_mcu.h.

● It is best to have an include file like project_mcu.h that all units #include. This file
should define the chip, speed, fuses and any other compiler settings that should be the
same for all units in the project.

● In this example project a #USE RS232 is in the project_mcu.h file. This creates an
RS232 library in each unit. The linker is able to determine the libraries are the same
and the duplicates removed in the final link.

● Each unit has its own error file (like filter_mcu.err). When the compilations are done in
a batch file it may be useful to terminate the batch run on the first error. The +CC
command line option will cause the compiler to return a windows error code if the
compilation fails. This can be tested in the batch file like this:

"c:\program files\picc\ccsc" +FM +CC +EXPORT report_mcu.c

if not errorlevel 1 goto abort
...
goto end
:abort
echo COMPILE ERROR
:end