MPLAB® X IDE

User’s Guide

 2011-2012 Microchip Technology Inc. DS52027B

Note the following details of the code protection feature on Microchip devices:
• Microchip products meet the specification contained in their particular Microchip Data Sheet.

• Microchip believes that its family of products is one of the most secure families of its kind on the market today, when used in the
intended manner and under normal conditions.

• There are dishonest and possibly illegal methods used to breach the code protection feature. All of these methods, to our
knowledge, require using the Microchip products in a manner outside the operating specifications contained in Microchip’s Data
Sheets. Most likely, the person doing so is engaged in theft of intellectual property.

• Microchip is willing to work with the customer who is concerned about the integrity of their code.

• Neither Microchip nor any other semiconductor manufacturer can guarantee the security of their code. Code protection does not
mean that we are guaranteeing the product as “unbreakable.”

Code protection is constantly evolving. We at Microchip are committed to continuously improving the code protection features of our
products. Attempts to break Microchip’s code protection feature may be a violation of the Digital Millennium Copyright Act. If such acts
allow unauthorized access to your software or other copyrighted work, you may have a right to sue for relief under that Act.

Information contained in this publication regarding device Trademarks

applications and the like is provided only for your convenience The Microchip name and logo, the Microchip logo, dsPIC,
and may be superseded by updates. It is your responsibility to FlashFlex, KEELOQ, KEELOQ logo, MPLAB, PIC, PICmicro,
ensure that your application meets with your specifications. PICSTART, PIC32 logo, rfPIC, SST, SST Logo, SuperFlash
MICROCHIP MAKES NO REPRESENTATIONS OR and UNI/O are registered trademarks of Microchip Technology
WARRANTIES OF ANY KIND WHETHER EXPRESS OR Incorporated in the U.S.A. and other countries.
IMPLIED, WRITTEN OR ORAL, STATUTORY OR
OTHERWISE, RELATED TO THE INFORMATION, FilterLab, Hampshire, HI-TECH C, Linear Active Thermistor,
INCLUDING BUT NOT LIMITED TO ITS CONDITION, MTP, SEEVAL and The Embedded Control Solutions
QUALITY, PERFORMANCE, MERCHANTABILITY OR Company are registered trademarks of Microchip Technology
FITNESS FOR PURPOSE. Microchip disclaims all liability Incorporated in the U.S.A.
arising from this information and its use. Use of Microchip Silicon Storage Technology is a registered trademark of
devices in life support and/or safety applications is entirely at Microchip Technology Inc. in other countries.
the buyer’s risk, and the buyer agrees to defend, indemnify and
Analog-for-the-Digital Age, Application Maestro, BodyCom,
hold harmless Microchip from any and all damages, claims,
chipKIT, chipKIT logo, CodeGuard, dsPICDEM,
suits, or expenses resulting from such use. No licenses are
dsPICDEM.net, dsPICworks, dsSPEAK, ECAN,
conveyed, implicitly or otherwise, under any Microchip
ECONOMONITOR, FanSense, HI-TIDE, In-Circuit Serial
intellectual property rights.
Programming, ICSP, Mindi, MiWi, MPASM, MPF, MPLAB
Certified logo, MPLIB, MPLINK, mTouch, Omniscient Code
Generation, PICC, PICC-18, PICDEM, PICDEM.net, PICkit,
PICtail, REAL ICE, rfLAB, Select Mode, SQI, Serial Quad I/O,
Total Endurance, TSHARC, UniWinDriver, WiperLock, ZENA
and Z-Scale are trademarks of Microchip Technology
Incorporated in the U.S.A. and other countries.
SQTP is a service mark of Microchip Technology Incorporated
in the U.S.A.
GestIC and ULPP are registered trademarks of Microchip
Technology Germany II GmbH & Co. & KG, a subsidiary of
Microchip Technology Inc., in other countries.
All other trademarks mentioned herein are property of their
respective companies.
© 2011-2012, Microchip Technology Incorporated, Printed in
the U.S.A., All Rights Reserved.
Printed on recycled paper.
ISBN: 978-1-62076-605-7

QUALITY MANAGEMENT SYSTEM Microchip received ISO/TS-16949:2009 certification for its worldwide
CERTIFIED BY DNV headquarters, design and wafer fabrication facilities in Chandler and
Tempe, Arizona; Gresham, Oregon and design centers in California
and India. The Company’s quality system processes and procedures
== ISO/TS 16949 == are for its PIC® MCUs and dsPIC® DSCs, KEELOQ® code hopping
devices, Serial EEPROMs, microperipherals, nonvolatile memory and
analog products. In addition, Microchip’s quality system for the design
and manufacture of development systems is ISO 9001:2000 certified.

DS52027B-page 2  2011-2012 Microchip Technology Inc.

 MPLAB® X IDE
USER’S GUIDE
Table of Contents

Preface ........................................................................................................................... 7
Chapter 1. What is MPLAB X IDE?
1.1 Introduction ................................................................................................... 11
1.2 An Overview of Embedded Systems ............................................................ 12
1.3 The Development Cycle ............................................................................... 19
1.4 Project Manager ........................................................................................... 20
1.5 Language Tools ............................................................................................ 21
1.6 Target Debugging ......................................................................................... 22
1.7 Device Programming .................................................................................... 23
1.8 Components of MPLAB X IDE ..................................................................... 24
1.9 MPLAB X IDE Online Help ........................................................................... 24
1.10 Other MPLAB X IDE Documentation .......................................................... 25
1.11 Web Site ..................................................................................................... 26
1.12 MPLAB X IDE Updates .............................................................................. 26
Chapter 2. Before You Begin
2.1 Introduction ................................................................................................... 27
2.2 Install JRE and MPLAB X IDE ...................................................................... 27
2.3 Install the USB Device Drivers (For Hardware Tools) .................................. 28
2.4 Connect to a Target (For Hardware Tools) .................................................. 31
2.5 Install the Language Tools ........................................................................... 31
2.6 Launch the IDE ............................................................................................. 32
2.7 Launch Multiple Instances of the IDE ........................................................... 35
Chapter 3. Tutorial
3.1 Introduction ................................................................................................... 37
3.2 Setting Up the Hardware and Software ........................................................ 38
3.3 Creating and Setting Up a Project ................................................................ 39
3.4 Running and Debugging Code ..................................................................... 55
Chapter 4. Basic Tasks
4.1 Introduction ................................................................................................... 63
4.2 Working with MPLAB X IDE Projects ........................................................... 63
4.3 Create a New Project ................................................................................... 64
4.4 View Changes to the Desktop ...................................................................... 72
4.5 View or Make Changes to Project Properties ............................................... 73
4.6 Set Options for Debugger, Programmer or Language Tools ........................ 74
4.7 Set Language Tool Locations ....................................................................... 76

 2011-2012 Microchip Technology Inc. DS52027B-page 3

MPLAB® X IDE User’s Guide

4.8 Set Other Tool Options ................................................................................. 77

4.9 Create a New File ......................................................................................... 77
4.10 Add Existing Files to a Project .................................................................... 79
4.11 Editor Usage ............................................................................................... 80
4.12 Add and Set Up Library and Object Files ................................................... 81
4.13 Set File Properties ...................................................................................... 83
4.14 Set Build Properties .................................................................................... 84
4.15 Build a Project ............................................................................................ 85
4.16 Run Code ................................................................................................... 86
4.17 Debug Run Code ........................................................................................ 87
4.18 Control Program Execution with Breakpoints ............................................. 88
4.19 Step Through Code .................................................................................... 91
4.20 Watch Symbol Values Change ................................................................... 92
4.21 Watch Local Variable Values Change ........................................................ 94
4.22 View/Change Device Memory (including Configuration Bits) ..................... 95
4.23 View the Call Stack .................................................................................... 98
4.24 Program a Device ....................................................................................... 98
Chapter 5. Additional Tasks
5.1 Introduction ................................................................................................... 99
5.2 Performing Additional Tasks ........................................................................ 99
5.3 Import MPLAB Legacy Project ................................................................... 100
5.4 Prebuilt Projects ......................................................................................... 102
5.5 Loadable Projects and Files ....................................................................... 103
5.6 Library Projects .......................................................................................... 106
5.7 Other Embedded Projects .......................................................................... 107
5.8 Sample Projects ......................................................................................... 107
5.9 Work with Other Types of Files .................................................................. 107
5.10 Modify or Create Code Templates ........................................................... 108
5.11 Switch Hardware or Language Tools ....................................................... 109
5.12 Use the Stopwatch ................................................................................... 110
5.13 View the Disassembly Window ................................................................ 110
5.14 View The Call Graph ................................................................................ 110
5.15 View the Dashboard Display .................................................................... 111
5.16 Improve Your Code .................................................................................. 112
5.17 Control Source Code ................................................................................ 113
5.18 Collaborate on Code Development and Error Tracking ........................... 115
5.19 Add Plug-In Tools ..................................................................................... 116
Chapter 6. Advanced Tasks
6.1 Introduction ................................................................................................. 119
6.2 Multiple Projects ......................................................................................... 119
6.3 Multiple Configurations ............................................................................... 121
6.4 Log Data ..................................................................................................... 124
6.5 Customize Toolbars ................................................................................... 125

DS52027B-page 4  2011-2012 Microchip Technology Inc.

 Table of Contents

Chapter 7. Editor
7.1 Introduction ................................................................................................. 133
7.2 Editor Usage ............................................................................................... 133
7.3 Editor Options ............................................................................................. 133
7.4 Editor Features of Note .............................................................................. 135
7.5 Code Folding .............................................................................................. 136
7.6 C Code Refactoring .................................................................................... 139
Chapter 8. Troubleshooting
8.1 Introduction ................................................................................................. 141
8.2 USB Driver Installation Issues .................................................................... 141
8.3 Cross-Platform Issues ................................................................................ 141
8.4 MPLAB X IDE Issues ................................................................................. 142
8.5 NetBeans Platform Issues .......................................................................... 143
8.6 Errors .......................................................................................................... 143
8.7 Forums ....................................................................................................... 144
Chapter 9. MPLAB X IDE vs. MPLAB IDE v8
9.1 Introduction ................................................................................................. 145
9.2 Major Differences ....................................................................................... 145
9.3 Menu Differences ....................................................................................... 148
9.4 Tool Support Differences ............................................................................ 154
Chapter 10. Desktop Reference
10.1 Introduction ............................................................................................... 155
10.2 Menus ....................................................................................................... 156
10.3 Toolbars ................................................................................................... 165
10.4 Status Bar ................................................................................................. 167
10.5 Grayed-out or Missing Items and Buttons ................................................ 167
Chapter 11. MPLAB X IDE Windows and Dialogs
11.1 Introduction ............................................................................................... 169
11.2 MPLAB X IDE Windows with Related Menus and Dialogs ....................... 169
11.3 MPLAB X IDE Wizards ............................................................................. 179
Chapter 12. NetBeans Windows and Dialogs
12.1 Introduction ............................................................................................... 181
12.2 NetBeans Specific Windows and Window Menus .................................... 181
12.3 NetBeans Specific Dialogs ....................................................................... 181
Chapter 13. Project Files and Folders
13.1 Introduction ............................................................................................... 183
13.2 Projects Window View .............................................................................. 183
13.3 Files Window View ................................................................................... 184
13.4 Importing an MPLAB IDE v8 Project – Relative Paths ............................. 186
13.5 Moving a Project ....................................................................................... 186
13.6 Building a Project Outside of MPLAB X IDE ............................................ 186

 2011-2012 Microchip Technology Inc. DS52027B-page 5

MPLAB® X IDE User’s Guide

Chapter 14. Configuration Settings Summary

14.1 Introduction ............................................................................................... 189
14.2 MPASM Toolchain .................................................................................... 189
14.3 HI-TECH® PICC™ Toolchain .................................................................. 191
14.4 HI-TECH® PICC-18™ Toolchain ............................................................. 191
14.5 C18 Toolchain .......................................................................................... 192
14.6 ASM30 Toolchain ..................................................................................... 192
14.7 C30 Toolchain .......................................................................................... 193
14.8 C32 Toolchain .......................................................................................... 195
14.9 XC Toolchains .......................................................................................... 195
Support .......................................................................................................................199
Glossary .....................................................................................................................203
Index ...........................................................................................................................221
Worldwide Sales and Service ...................................................................................226

DS52027B-page 6  2011-2012 Microchip Technology Inc.

 MPLAB® X IDE
USER’S GUIDE
Preface

INTRODUCTION
This chapter contains general information that will be useful to know before using
MPLAB® X IDE. Items discussed include:
• Document Layout
• Conventions Used
• Recommended Reading

DOCUMENT LAYOUT
This document describes how to use the MPLAB X IDE. The manual layout is as
follows:
• Chapter 1. “What is MPLAB X IDE?” – An overview of what the MPLAB X IDE is
and where help can be found.
• Chapter 2. “Before You Begin” – Describes how to install USB drivers for
hardware tools and language toolsuites for compiling/assembling code.
• Chapter 3. “Tutorial” – Provides step-by-step descriptions of features for using
MPLAB X IDE.
• Chapter 4. “Basic Tasks” – Describes how to use the basic features of MPLAB
X IDE. It is similar to the Tutorial chapter but with more detail.
• Chapter 5. “Additional Tasks” – Describes how to use additional features of
MPLAB X IDE, i.e., importing MPLAB IDE v8 projects or using the stopwatch.
• Chapter 6. “Advanced Tasks” – Describes how to use the advanced features of
MPLAB X IDE, i.e., working with multiple projects and project configurations.
• Chapter 8. “Troubleshooting” – Discusses troubleshooting techniques.
• Chapter 9. “MPLAB X IDE vs. MPLAB IDE v8” – Explains the major, feature,
menu, and tool support differences between MPLAB X IDE and MPLAB IDE v8.
• Chapter 10. “Desktop Reference” – Provides a reference to MPLAB X IDE
desktop items, including menus, toolbars, and the status bar.
• Chapter 11. “MPLAB X IDE Windows and Dialogs” – References NetBeans™
windows and dialogs and discusses the windows and dialogs that are unique to
MPLAB X IDE.
• Chapter 13. “Project Files and Folders” – Explains the folder structure and
locations of project files.
• Chapter 14. “Configuration Settings Summary” – Shows how to set Configura-
tion bits in code for supported language tools. This is required in MPLAB X IDE as
the Configurations Settings window only temporarily sets the bits for debug.

 2011-2012 Microchip Technology Inc. DS52027B-page 7

MPLAB® X IDE User’s Guide

CONVENTIONS USED
The following conventions may appear in this documentation:

DOCUMENTATION CONVENTIONS
Description Represents Examples
Arial font:
Italic Referenced books MPLAB® IDE User’s Guide
Emphasized text ...is the only compiler...
Initial caps A window the Output window
A dialog the Settings dialog
A menu selection select Enable Programmer
Quotes A field name in a window or “Save project before build”
dialog, or an individual menu
item
Underlined, italic with right A path in text File>Save
angle bracket between text
Right angle bracket between A path in a table cell File>Save
text
Bold characters A dialog button Click OK
A tab Click the Power tab
Text in angle brackets < > A key on the keyboard Press <Enter>, <F1>
Courier New font:
Plain Sample source code #define START
Filenames autoexec.bat
File paths c:\mcc18\h
Keywords _asm, _endasm, static
Command-line options -Opa+, -Opa-
Bit values 0, 1
Constants 0xFF,’A’
Italic A variable argument file.o, where file can be
any valid filename
Square brackets [ ] Optional arguments mpasmwin [options]
file [options]
Curly brackets and pipe Choice of mutually exclusive errorlevel {0|1}
character: { | } arguments; an OR selection
Ellipses... Replaces repeated text var_name [,
var_name...]
Represents code supplied by void main (void)
user { ...
}

DS52027B-page 8  2011-2012 Microchip Technology Inc.

 Preface

RECOMMENDED READING
This user’s guide describes how to use MPLAB X IDE. Other useful documents are
listed below. The following Microchip documents are available and recommended as
supplemental reference resources.
Readme for MPLAB IDE
For the latest information on using MPLAB X IDE, read the release notes under the
“Release Notes and Support Documentation” heading on the Start page. The release
notes contain update information and known issues that may not be included in this
user’s guide.
Readme Files
For the latest information on using other tools, read the tool-specific Readme files in
the Readmes subdirectory of the MPLAB X IDE installation directory. The Readme files
contain update information and known issues that may not be included in this user’s
guide.
Online Help Files
Comprehensive help files are available for MPLAB X IDE, MPLAB Editor and MPLAB
SIM simulator. Tutorials, functional descriptions and reference material are included.
Device Data Sheets and Family Reference Manuals
See the Microchip web site, http://www.microchip.com, for complete and updated ver-
sions of PIC® MCU and dsPIC® DSC data sheets and related device family reference
manuals.

 2011-2012 Microchip Technology Inc. DS52027B-page 9

MPLAB® X IDE User’s Guide
NOTES:

DS52027B-page 10  2011-2012 Microchip Technology Inc.

 MPLAB® X IDE
USER’S GUIDE
Chapter 1. What is MPLAB X IDE?
1.1 INTRODUCTION
MPLAB® X IDE is a software program that is used to develop applications for Microchip
microcontrollers and digital signal controllers. (Experienced embedded-systems
designers may want to skip to the next chapter.)
This development tool is called an Integrated Development Environment, or IDE,
because it provides a single integrated “environment” to develop code for embedded
microcontrollers.
This chapter describes the development of an embedded system and briefly explains
how MPLAB X IDE from Microchip is used in the process.
Topics covered here are:
• An Overview of Embedded Systems
• The Development Cycle
• Project Manager
• Language Tools
• Target Debugging
• Device Programming
• Components of MPLAB X IDE
• MPLAB X IDE Online Help
• Other MPLAB X IDE Documentation
• Web Site
• MPLAB X IDE Updates

 2011-2012 Microchip Technology Inc. DS52027B-page 11

MPLAB® X IDE User’s Guide

1.2 AN OVERVIEW OF EMBEDDED SYSTEMS

An embedded system is typically a design that uses the power of a small microcon-
troller, like the Microchip PIC microcontroller (MCU) or dsPIC digital signal controller
(DSC). These microcontrollers combine a microprocessor unit (like the CPU in a per-
sonal computer) with some additional circuits called peripherals, plus some additional
circuits on the same chip to make a small control module requiring few other external
devices. This single device can then be embedded into other electronic and
mechanical devices for low-cost digital control.

1.2.1 Differences Between an Embedded Controller and a Personal

Computer
The main difference between an embedded controller and a personal computer is that
the embedded controller is dedicated to one specific task or set of tasks. A personal
computer is designed to run many different types of programs and to connect to many
different external devices. An embedded controller has a single program and, as a
result, can be made cheaply to include just enough computing power and hardware to
perform that dedicated task.
A personal computer has a relatively expensive generalized central processing unit
(CPU) at its heart with many other external devices (memory, disk drives, video con-
trollers, network interface circuits, etc.). An embedded system has a low-cost micro-
controller unit (MCU) for its intelligence, with many peripheral circuits on the same chip,
and with relatively few external devices.
Often, an embedded system is an invisible part, or sub-module of another product,
such as a cordless drill, refrigerator or garage door opener. The controller in these
products does a tiny portion of the function of the whole device. The controller adds
low-cost intelligence to some of the critical sub-systems in these devices.
An example of an embedded system is a smoke detector. Its function is to evaluate sig-
nals from a sensor and sound an alarm if the signals indicate the presence of smoke.
A small program in the smoke detector either runs in an infinite loop, sampling the sig-
nal from the smoke sensor, or lies dormant in a low-power “Sleep” mode, being awak-
ened by a signal from the sensor. The program then sounds the alarm. The program
would possibly have a few other functions, such as a user test function, and a low bat-
tery alert.
While a personal computer with a sensor and audio output could be programmed to do
the same function, it would not be a cost-effective solution (nor would it run on a
nine-volt battery, unattended for years!). Embedded designs use inexpensive micro-
controllers to put intelligence into the everyday things in our environment, such as
smoke detectors, cameras, cell phones, appliances, automobiles, smart cards and
security systems.

DS52027B-page 12  2011-2012 Microchip Technology Inc.

 What is MPLAB® IDE?

1.2.2 Components of a Microcontroller

The PIC MCU has on-chip program memory for the firmware, or coded instructions, to
run a program (Figure 1-1). A Program Counter (PC) is used to address program mem-
ory, including reset and interrupt addresses. A hardware stack is used with call and
return instructions in code, so it works with, but is not part of, program memory. Device
data sheets describe the details of program memory operation, vectors and the stack.

FIGURE 1-1: PIC® MCU DATA SHEET – PROGRAM MEMORY AND STACK

PC<12:0>

CALL, RETURN 13
RETFIE, RETLW

Stack Level 1
Stack Level 2

Stack Level 8

Reset Vector 0000h

Interrupt Vector 0004h

0005h
Page 0
On-Chip
07FFh
Program
0800h
Memory
Page 1
0FFFh
1000h

Access 0-FFFh

1FFFh

The microcontroller also has data or “file register” memory. This memory consists of
Special Function Registers (SFRs) and General Purpose Registers (GPRs) as shown
in Figure 1-3. SFRs are registers used by the CPU and peripheral functions for control-
ling the desired operation of the device. GPRs are for storage of variables that the pro-
gram will need for computation or temporary storage. Some microcontrollers have
additional data EEPROM memory. As with program memory, device data sheets
describe the details of data memory use and operation.

 2011-2012 Microchip Technology Inc. DS52027B-page 13

MPLAB® X IDE User’s Guide
FIGURE 1-2: PIC® MCU DATA SHEET – FILE REGISTERS
File File File File
Address Address Address Address
Indirect addr. (1) 00h Indirect addr. (1) 80h Indirect addr. (1) 100h Indirect addr. (1) 180h
TMR0 01h OPTION_REG 81h TMR0 101h OPTION_REG 181h
PCL 02h PCL 82h PCL 102h PCL 182h
STATUS 03h STATUS 83h STATUS 103h STATUS 183h
FSR 04h FSR 84h FSR 104h FSR 184h
PORTA 05h TRISA 85h PORTA 105h TRISA 185h
PORTB 06h TRISB 86h PORTB 106h TRISB 186h
PORTC 07h TRISC 87h PORTC 107h TRISC 187h
08h 88h 108h 188h
09h 89h 109h 189h
PCLATH 0Ah PCLATH 8Ah PCLATH 10Ah PCLATH 18Ah
INTCON 0Bh INTCON 8Bh INTCON 10Bh INTCON 18Bh
PIR1 0Ch PIE1 8Ch EEDAT 10Ch EECON1 18Ch
PIR2 0Dh PIE2 8Dh EEADR 10Dh EECON2(1) 18Dh
TMR1L 0Eh PCON 8Eh EEDATH 10Eh 18Eh
TMR1H 0Fh OSCCON 8Fh EEADRH 10Fh 18Fh
T1CON 10h OSCTUNE 90h 110h 190h
TMR2 11h 91h 111h 191h
T2CON 12h PR2 92h 112h 192h
SSPBUF 13h SSPADD(2) 93h 113h 193h
SSPCON 14h SSPSTAT 94h 114h 194h
CCPR1L 15h WPUA 95h WPUB 115h 195h
CCPR1H 16h IOCA 96h IOCB 116h 196h
CCP1CON 17h WDTCON 97h 117h 197h
RCSTA 18h TXSTA 98h VRCON 118h 198h
TXREG 19h SPBRG 99h CM1CON0 119h 199h
RCREG 1Ah SPBRGH 9Ah CM2CON0 11Ah 19Ah
1Bh BAUDCTL 9Bh CM2CON1 11Bh 19Bh
PWM1CON 1Ch 9Ch 11Ch 19Ch
ECCPAS 1Dh 9Dh 11Dh PSTRCON 19Dh
ADRESH 1Eh ADRESL 9Eh ANSEL 11Eh SRCON 19Eh
ADCON0 1Fh ADCON1 9Fh ANSELH 11Fh 19Fh
20h A0h 120h 1A0h

General General
General Purpose Purpose
Purpose Register Register
Register
80 Bytes 80 Bytes
96 Bytes EFh 16Fh
accesses F0h accesses 170h accesses 1F0h
7Fh 70h-7Fh FFh 70h-7Fh 17Fh 70h-7Fh 1FFh
Bank 0 Bank 1 Bank 2 Bank 3

Unimplemented data memory locations, read as ‘0’.

Note 1: Not a physical register.
2: Address 93h also accesses the SSP Mask (SSPMSK) register under certain conditions.

DS52027B-page 14  2011-2012 Microchip Technology Inc.

 What is MPLAB® IDE?
In addition to memory, the microcontroller has a number of peripheral device circuits on
the same chip. Some peripheral devices are called input/output (I/O) ports. I/O ports
are pins on the microcontroller that can be used as outputs and driven high or low to
send signals, blink lights, drive speakers – just about anything that can be sent through
a wire. Often these pins are bidirectional and can also be configured as inputs allowing
the program to respond to an external switch, sensor or to communicate with some
external device.

FIGURE 1-3: PIC® MCU DATA SHEET – BLOCK DIAGRAM (EXCERPT)

Data Bus<8>
PORTA
RA0/AN0
RA1/AN1
Table Pointer<21> Data Latch
21 RA2/AN2/VREF-
8 8 RA3/AN3/VREF+
Inc/Dec Logic Data RAM RA4/T0CKI
21
RA5/AN4/LVDIN
Address Latch RA6
21 PCLATU PCLATH 12 PORTB
RB0/INT0
Address<12>
PCU PCH PCL RB1/INT1
Program Counter 12 4 RB2/INT2
4
BSR
RB3/INT3
Address Latch FSR0 Bank0, F
RB4/KBI0
Program FSR1 RB5/KBI1/PGM
31 Level Stack
Memory FSR2 RB6/KBI2/PGC
12
RB7/KBI3/PGD
Data Latch
Inc/Dec
Decode Logic
Table Latch PORTC
RC0/T1OSO/T13CKI
RC1/T1OSI/CCP2
16 8
RC2/CCP1
ROM Latch
RC3/SCK/SCL
RC4/SDI/SDA
RC5/SDO
IR
RC6/TX1/CK1
RC7/RX1/DT1

In order to design such a system, it must be decided which peripherals are needed for
an application.

Analog-to-Digital Converters (ADCs) allow microcontrollers to connect to sensors and

receive changing voltage levels.
Serial communication peripherals allow you to stream communications over a few
wires to another microcontroller, to a local network or to the internet.

Peripherals on the PIC MCU called “timers” accurately measure signal events and gen-
erate and capture communications signals, produce precise waveforms, even auto-
matically reset the microcontroller if it gets “hung” or lost due to a power glitch or
hardware malfunction.

Other peripherals detect if the external power is dipping below dangerous levels so the
microcontroller can store critical information and safely shut down before power is
completely lost.
The peripherals and the amount of memory an application needs to run a program
largely determines which PIC MCU to use. Other factors might include the power con-
sumed by the microcontroller and its “form factor,” i.e., the size and characteristics of
the physical package that must reside on the target design.

 2011-2012 Microchip Technology Inc. DS52027B-page 15

MPLAB® X IDE User’s Guide
FIGURE 1-4: EXAMPLE PIC® MCU DEVICE PACKAGE
E
E1
#leads=n1

D1 D

2
1
B
n
CH x 45

A
c
A2

L 
 A1
(F)

1.2.3 Implementing an Embedded System Design with MPLAB X IDE

A development system for embedded controllers is a system of programs running on a
computer to help write, edit, debug and program code – the intelligence of embedded
systems applications – into a microcontroller. MPLAB X IDE is such a system; it con-
tains all the components needed to design and deploy embedded systems applica-
tions.
The typical tasks for developing an embedded controller application are:
1. Create the high level design. From the features and performance desired, decide
which PIC MCU or dsPIC DSC device is best suited to the application, then
design the associated hardware circuitry. After determining which peripherals
and pins control the hardware, write the firmware – the software that will control
the hardware aspects of the embedded application. A language tool such as an
assembler, which is directly translatable into machine code, or a compiler that
allows a more natural language for creating programs, should be used to write
and edit code. Assemblers and compilers help make the code understandable,
allowing function labels to identify code routines with variables that have names
associated with their use, and with constructs that help organize the code in a
maintainable structure.

FIGURE 1-5: PIC® MCU DATA SHEET – TIMING (EXCERPT)

Q1 Q2 Q3 Q4 Q1 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1
TT1P

T1OSI 1 2 3 4 5 6 7 8
TSCS
OSC1

Internal TOSC
System
Clock TDLY
SCS
(OSCCON<0>)
Program PC PC + 2 PC + 4
Counter

DS52027B-page 16  2011-2012 Microchip Technology Inc.

 What is MPLAB® IDE?
FIGURE 1-6: PIC® MCU DATA SHEET – INSTRUCTIONS (EXCERPT)

2. Compile, assemble and link the software using the assembler and/or compiler
and linker to convert your code into “ones and zeroes” – machine code for the
PIC MCUs. This machine code will eventually become the firmware (the code
programmed into the microcontroller).
3. Test your code. Usually a complex program does not work exactly the way
imagined, and “bugs” need to be removed from the design to get proper results.
The debugger allows you to see the “ones and zeroes” execute, related to the
source code you wrote, with the symbols and function names from your program.
Debugging allows you to experiment with your code to see the value of variables
at various points in the program, and to do “what if” checks, changing variable
values and stepping through routines.
4. “Burn” the code into a microcontroller and verify that it executes correctly in the
finished application.
Of course, each of these steps can be quite complex. The important thing is to concen-
trate on the details of your own design, while relying upon MPLAB X IDE and its com-
ponents to get through each step without continuously encountering new learning
curves.

 2011-2012 Microchip Technology Inc. DS52027B-page 17

MPLAB® X IDE User’s Guide
Step 1 is driven by the designer, although MPLAB X IDE can help in modeling circuits
and code so that crucial design decisions can be made.
MPLAB X IDE really helps with steps 2 through 4. Its Programmer’s Editor helps write
correct code with the language tools of choice. The editor is aware of the assembler
and compiler programming constructs and automatically “color-keys” the source code
to help ensure it is syntactically correct. The Project Manager enables you to organize
the various files used in your application: source files, processor description header
files and library files. When the code is built, you can control how rigorously code will
be optimized for size or speed by the compiler and where individual variables and pro-
gram data will be programmed into the device. You can also specify a “memory model”
in order to make the best use of the microcontroller’s memory for your application. If
the language tools run into errors when building the application, the offending line is
shown and can be double clicked to go to the corresponding source file for immediate
editing. After editing, you will rebuild and try your application again. Often this
write-compile-fix loop is done many times for complex code as the sub-sections are
written and tested. MPLAB X IDE goes through this loop with maximum speed, allowing
you to get on to the next step.
Once the code builds with no errors, it needs to be tested. MPLAB X IDE has compo-
nents called “debuggers” and free software simulators for all PIC MCU and dsPIC DSC
devices to help test the code. Even if the hardware is not yet finished, you can begin
testing the code with the simulator, a software program that simulates the execution of
the microcontroller. The simulator can accept a simulated input (stimulus), in order to
model how the firmware responds to external signals. The simulator can measure code
execution time, single step through code to watch variables and peripherals, and trace
the code to generate a detailed record of how the program ran.
Once the hardware is in a prototype stage, a hardware debugger, such as an in-circuit
emulator or an in-circuit debugger, can be used. These debug tools run the code in real
time on your actual application by using special circuitry built into many devices with
Flash program memory. They can “see into” the target microcontrollers program and
data memory, and stop and start program execution, allowing you to test the code with
the microcontroller in place on the application.
After the application is running correctly, you can program a microcontroller with one of
Microchip’s devices or development programmers. These programmers verify that the
finished code will run as designed. MPLAB X IDE supports most PIC MCUs and all
dsPIC DSCs.

DS52027B-page 18  2011-2012 Microchip Technology Inc.

 What is MPLAB® IDE?

1.3 THE DEVELOPMENT CYCLE

The process for writing an application is often described as a development cycle, since
it is rare that all the steps from design to implementation can be done flawlessly the first
time. More often code is written, tested and then modified in order to produce an appli-
cation that performs correctly.
The Integrated Development Environment allows the embedded systems design engi-
neer to progress through this cycle without the distraction of switching among an array
of tools. By using MPLAB X IDE, all the functions are integrated, allowing the engineer
to concentrate on completing the application without the interruption of separate tools
and different modes of operation.

FIGURE 1-7: THE DESIGN CYCLE

Compile/Assemble/
Link Code Download Code to
Debugger

Edit/Create/Design Analyze/Debug
Source Code Code

MPLAB X IDE is a “wrapper” that coordinates all the tools from a single graphical user
interface, usually automatically. For instance, once code is written, it can be converted
to executable instructions and downloaded into a microcontroller to see how it works.
In this process multiple tools are needed: an editor to write the code, a project manager
to organize files and settings, a compiler or assembler to convert the source code to
machine code and some sort of hardware or software that either connects to a target
microcontroller or simulates the operation of a microcontroller.

 2011-2012 Microchip Technology Inc. DS52027B-page 19

MPLAB® X IDE User’s Guide

1.4 PROJECT MANAGER

The project manager organizes the files to be edited and other associated files so they
can be sent to the language tools for assembly or compilation, and ultimately to a linker.
The linker has the task of placing the object code fragments from the assembler, com-
piler and libraries into the proper memory areas of the embedded controller, and ensure
that the modules function with each other (or are “linked”).
This entire operation from assembly and compilation through the link process is called
a project “build”. Properties specified for the language tools can be invoked differently
for each file, if desired, and a build process integrates all of the language tools’
operations.

FIGURE 1-8: MPLAB® X IDE PROJECT MANAGER

Source
Files

Individual
Build
Options
Object
File
Libraries
Assembler Compiler

Linker
Script

Linker

Debug Executable
File File

The source files are text files that are written conforming to the rules of the assembler
or compiler. The assembler and compiler convert them into intermediate modules of
machine code and placeholders for references to functions and data storage.
The linker resolves these placeholders and combines all the modules into a file of exe-
cutable machine code. The linker also produces a debug file which allows MPLAB X
IDE to relate the executing machine codes back to the source files.
A text editor is used to write the code. It recognizes the constructs in the text and uses
color coding to identify various elements, such as instruction mnemonics, C language
constructs and comments. The editor supports operations commonly used in writing
source code. After the code is written, the editor works with the other tools to display
code execution in the debugger. Breakpoints (which stop or “break” the execution of
code) can be set in the editor, and the values of variables can be inspected by hovering
the mouse pointer over the variable name. Names of variables can be dragged from
source text windows and then dropped into a Watch window where their changing
values can be watched after each breakpoint or during code execution.

DS52027B-page 20  2011-2012 Microchip Technology Inc.

 What is MPLAB® IDE?

1.5 LANGUAGE TOOLS

Language tools are programs such as cross-assemblers and cross-compilers. Most
people are familiar with some of the language tools that run on a computer, i.e., Visual
Basic or C compilers.
When using language tools for embedded systems, a “cross-assembler” or
“cross-compiler” is used. These tools differ from typical compilers in that they run on a
computer, but they produce code to run on another microprocessor (or microcontroller).
Language tools also produce a debug file that MPLAB X IDE uses to correlate the
machine instructions and memory locations with the source code. This bit of integration
allows the MPLAB X IDE editor to set breakpoints, allows Watch windows to view vari-
able contents, and lets you single step through the source code, while watching the
application execute.
Embedded system language tools also differ somewhat from compilers that run and
execute on a computer because they must be very space conscious. The smaller the
code produced, the better, because that provides the smallest possible memory usage
for the target, which reduces cost. This means that techniques to optimize and enhance
the code, using machine-specific knowledge, are desirable.

The size of programs for computers typically extends into the megabytes for moder-
ately complex programs. The size of simple embedded systems programs may be as
small as a thousand bytes or less. A medium size embedded system might need 32K
or 64K of code for relatively complex functions. Some embedded systems use
megabytes of storage for large tables, user text messages or data logging.

FIGURE 1-9: A COMPILER CONVERTS SOURCE CODE INTO MACHINE

INSTRUCTIONS

int main (void)

{ 01101111
counter = 1; 10001000
TRISB =0; 11001101
while (input1 = 0) 10100001
COMPILER
{ 00110011
PORTB = count; 01011101
counter++; 00110001
} 11100101
}

 2011-2012 Microchip Technology Inc. DS52027B-page 21

MPLAB® X IDE User’s Guide

1.6 TARGET DEBUGGING

In a development environment, the execution of the code is tested on a debugger. The
debugger can be a software program that simulates the operation of the microcontroller
for testing, or it can be a hardware instrument to analyze the program as it executes in
the application.

1.6.1 Software Debuggers

Simulators are built into MPLAB X IDE so a program can be tested without any addi-
tional hardware. A simulator is a software debugger, and the debugger functions for the
simulator are almost identical to the hardware debuggers, allowing a new tool to be
learned with ease. Usually, a simulator runs somewhat slower than an actual microcon-
troller, since the CPU in the computer is being used to simulate the operations of the
microcontroller.

1.6.2 Hardware Debuggers

There are two types of hardware that can be used with MPLAB X IDE: programmers
and hardware debuggers. A programmer simply burns the machine code from the PC
into the internal memory of the target microcontroller. The microcontroller can then be
plugged into the application and, hopefully, it will run as designed.
Usually, however, the code does not function exactly as anticipated, and the engineer
is tasked with reviewing the code and its operation in the application to determine how
to modify the original source code to make it execute as desired. This process is called
debugging. As noted previously, the simulator can be used to test how the code will
operate, but once a microcontroller is programmed with the firmware, many things out-
side the scope of the simulator come into play. Using just a programmer, the code could
be changed, reprogrammed into the microcontroller and plugged into the target for
retest, but this could be a long, laborious cycle if the code is complex, and it is difficult
to understand exactly what is going wrong in the hardware.
This is where a hardware debugger is useful. Hardware debuggers can be in-circuit
emulators or in-circuit debuggers, which use microcontrollers that have special built-in
debugging features. A hardware debugger, like a simulator, allows the engineer to
inspect variables at various points in the code, and single step to follow instructions as
the hardware interacts with its specialized circuitry.

1.6.3 Integrated Development Environment

Debugging usually becomes urgent near the end of the project design cycle. As dead-
lines loom, getting the application to function as originally designed is the last step
before going into deployment of the product, and often has the most influence on pro-
ducing delays in getting a product out. That’s where an integrated development envi-
ronment is most important. Doing fine “tweaks” to the code, recompiling, downloading
and testing all require time. Using all tools within a single environment will reduce the
time around the “cycle.” These last steps, where critical bugs are worked out, are a test
for the embedded systems designer. The right tool can save time. With MPLAB X IDE
many tools can be selected, but they all will have a similar interface, and the learning
curve from simulator to low-cost in-circuit debugger to powerful in-circuit emulator is
small.

DS52027B-page 22  2011-2012 Microchip Technology Inc.

 What is MPLAB® IDE?

1.7 DEVICE PROGRAMMING

After the application has been debugged and is running in the development environ-
ment, it needs to be tested on its own. A device can be programmed with an in-circuit
emulator, an in-circuit debugger, a development programmer, or a device programmer.
MPLAB X IDE can be set to the programmer function, and the part can be “burned”.
The target application can now be observed in its nearly final state. Engineering proto-
type programmers allow quick prototypes to be made and evaluated. Some applica-
tions can be programmed after the device is soldered on the target PC board. Using
In-Circuit Serial Programming™ (ICSP™) programming capability, the firmware can be
programmed into the application at the time of manufacture, allowing updated revisions
to be programmed into an embedded application later in its life cycle. Devices that sup-
port in-circuit debugging can even be plugged back into an in-circuit debugger after
manufacturing for quality tests and development of next generation firmware.
Production programming can be accomplished using a production programmer and the
MPLAB IPE, which is installed with MPLAB X IDE.

 2011-2012 Microchip Technology Inc. DS52027B-page 23

MPLAB® X IDE User’s Guide

1.8 COMPONENTS OF MPLAB X IDE

MPLAB X IDE includes:
• a full-featured programmer’s text editor that also serves as a window into the
debugger.
• a project manager (visible as the Project window) that provides integration and
communication between the IDE and the language tools.
• a number of assembler/linker suites for the development of firmware for your proj-
ect’s device.
• a debugger engine that provides breakpoints, single stepping, Watch windows
and all the features of a modern debugger. The debugger works in conjunction
with debug tools, both software and hardware.
• a software simulator for all PIC MCU and dsPIC DSC devices. The simulator is
actually composed of several device-specific simulator executables. MPLAB X
IDE decides which one to use based on your project’s device.
Optional components can be acquired or purchased to work with the MPLAB X IDE:
• Compiler Language Tools
MPLAB XC C compilers from Microchip provide fully integrated, optimized code for PIC
MCUs and dsPIC DSCs. Along with compilers from microEngineering Labs, CCS and
SDCC, they are invoked by the MPLAB X IDE project manager to compile code that is
automatically loaded into the target debugger for instant testing and verification.
• Programmers
PICkit™ 2, PICkit 3 and MPLAB ICD 3 in-circuit debuggers, and MPLAB REAL ICE™
in-circuit emulator, can program code into target devices. MPLAB X IDE offers full con-
trol over programming both code and data, as well as the Configuration bits to set the
various operating modes of the target microcontrollers or digital signal controllers.
MPLAB PM3 device programmer can be used with MPLAB IPE after development is
complete.
• In-Circuit Debuggers and Emulators
PICkit™ 2, PICkit 3 and MPLAB ICD 3 in-circuit debuggers, and MPLAB REAL ICE™
in-circuit emulator can be used to debug application code on target devices. By using
some of the on-chip resources, they can download code into a target microcontroller
inserted in the application, set breakpoints, single step and monitor registers and
variables. The emulator includes additional debug features, such as trace.
• Plug-In Tools
Several plug-ins are available to add to the capabilities for MPLAB X IDE. For example,
the Data Monitor and Control Interface (DMCI) provides a mechanism to view and con-
trol variables in code and change their values real-time. It also allows you to view output
data in a graphical format.

1.9 MPLAB X IDE ONLINE HELP

MPLAB X IDE is built upon the NetBeans platform. Therefore, many of the NetBeans
functions are now MPLAB X IDE functions.
Please refer to all help files for a complete understanding of MPLAB X IDE behavior.
To launch help, select Help>Help Contents.
For NetBeans information, see the online help files under “NetBeans Help” in the table
of contents. For all MPLAB X IDE development tool information, see the online help
files under “MPLAB X IDE Help” in the table of contents.
For a comparison of MPLAB X IDE and MPLAB IDE v8, see Chapter 9. “MPLAB X
IDE vs. MPLAB IDE v8”.

DS52027B-page 24  2011-2012 Microchip Technology Inc.

 What is MPLAB® IDE?

1.10 OTHER MPLAB X IDE DOCUMENTATION

In addition to help, links to other documentation, as well as videos and forums, may be
found on the Start Page (Figure 1-10).
Also, documentation on our website may be useful:
http://www.microchip.com/devtools

FIGURE 1-10: MPLAB X IDE START PAGE

 2011-2012 Microchip Technology Inc. DS52027B-page 25

MPLAB® X IDE User’s Guide

1.11 WEB SITE

Microchip provides online support via our web site at http://www.microchip.com. This
web site is used as a means to make files and information easily available to
customers. For more details, see Support.

1.12 MPLAB X IDE UPDATES

MPLAB X IDE is an evolving program with thousands of users. Microchip Technology
is continually designing new microcontrollers with new features. Many new MPLAB X
IDE features come from customer requests and from internal usage. Continued new
designs and the release of new microcontrollers ensure that MPLAB X IDE will con-
tinue to evolve.
MPLAB X IDE is scheduled for a version update approximately every few months to
add new device support and new features.
For projects that are midway through development when a new version of MPLAB X
IDE is released, it is considered “best practice” to not update to the new release unless
there is a compelling reason to do so, such as a bug fix on a bug that inhibits the current
efforts. The start of a new project is the best time to update to a new release.
Each new release of the MPLAB X IDE software has new features implemented, so the
printed documentation will inevitably “lag” the online help. The online help is the best
source for any questions about MPLAB X IDE.
To be notified of updates to MPLAB X IDE and its components, subscribe to the
Development Tools section of myMICROCHIP Personalized Notification Service on
http://www.microchip.com/pcn. For more details, see Support.

DS52027B-page 26  2011-2012 Microchip Technology Inc.

 MPLAB® X IDE
USER’S GUIDE
Chapter 2. Before You Begin
2.1 INTRODUCTION
Before you can use MPLAB X IDE you must perform the following tasks:
• Install JRE and MPLAB X IDE
• Install the USB Device Drivers (For Hardware Tools)
• Connect to a Target (For Hardware Tools)
• Install the Language Tools
• Launch the IDE
• Launch Multiple Instances of the IDE

2.2 INSTALL JRE AND MPLAB X IDE

When you install MPLAB X IDE (based on the NetBeans platform), the correct Java
Runtime Environment (JRE) for Windows and Linux OS will be installed. For Mac OS,
if the correct JRE is already installed, the MPLAB X IDE install will proceed. If not, you
will be prompted by a dialog where to acquire the correct version. Follow the instruc-
tions, install the JRE, and then install MPLAB X IDE.

 2011-2012 Microchip Technology Inc. DS52027B-page 27

MPLAB® X IDE User’s Guide

2.3 INSTALL THE USB DEVICE DRIVERS (FOR HARDWARE TOOLS)

For correct tool operation, you may need to install USB drivers.

2.3.1 USB Driver Installation for Mac or Linux Operating Systems

When you install MPLAB X IDE on a Mac or Linux box, the installer will place the USB
drivers for you. You do not need to do anything.

2.3.2 USB Driver Installation for Windows® 2000/XP/Vista/7 Operating

Systems
When you install MPLAB X IDE on a Windows personal computer, you will need to fol-
low the instructions below to correctly install the USB drivers. The USB hardware tool
drivers for MPLAB IDE v8.xx are not the same as those for MPLAB X IDE.
These instructions apply to the following tools:
• MPLAB REAL ICE in-circuit emulator
• MPLAB ICD 3 in-circuit debugger
• MPLAB PM3 device programmer
• PIC32 Starter Kit (for 32-bit operating systems only prior to Beta 7.10)
You do not need to do anything for PICkit 2, PICkit 3 or other MPLAB Starter Kits.
To install and update USB drivers, you can use a GUI application called MPDDSwitch
(32-bit OS) or MPDDSwitch64 (64-bit OS). This should be available as the desktop icon
MPLAB Driver Switcher.

FIGURE 2-1: SWITCHER UTILITY

If this does not work, you can:

1. specify the paths to the driver files by clicking Advanced and running the
switcher again.
2. install the drivers manually.
Follow the instructions below to determine your installation method.

DS52027B-page 28  2011-2012 Microchip Technology Inc.

 Before You Begin
2.3.2.1 BEFORE YOU INSTALL THE DRIVERS
Whether you use the Switcher or activate the preinstaller to install your drivers (as dis-
cussed in the next sections), be aware that your system’s version of WinUSB drivers
will be replaced if they are older than the Switcher or preinstaller version. If you want
to keep your version of WinUSB drivers, rename these files before installing any Micro-
chip device driver.
The WinUSB driver is located at:
32-bit OS
C:\Windows\system32\WinUSB.dll (32-bit)
C:\Windows\system32\drivers\WinUSB.sys (64-bit)
64-bit OS
C:\Windows\SysWOW64\WinUSB.dll (32-bit)
C:\Windows\system32\WinUSB.dll (64-bit)
C:\Windows\system32\drivers\WinUSB.sys (64-bit)

2.3.2.2 IF YOU HAVE WINDOWS 7 OS, USE ADMINISTRATOR MODE

If you will use the Switcher executable to install your device drivers, you must be in
Administrator mode to run this program on Windows 7 OS.
To run the Device Driver Switcher GUI application as administrator, right click on the
executable – MPDDSwitch.exe or MPDDSwitch64.exe – and select ‘Run as Admin-
istrator’.
It is recommended that you use the GUI application first to switch the drivers. If this is
problematic, you may switch the drivers using command-line applications.
To run the command-line application – mchpdds32.exe or mchpdds64.exe – as
administrator, first open the command prompt in Admin mode: Start>All
Programs>Accessories>Command Prompt, right click and select ‘Run as Administra-
tor’. This will open up the Administrator: Command Prompt. After this, the instructions
provided in the ReadMe32.txt or ReadMe64.txt file may be followed to complete
the driver switching.

2.3.2.3 IF MPLAB IDE V8.XX IS ALREADY INSTALLED ON YOUR SYSTEM

If MPLAB IDE v8.xx or earlier is already installed on your computer, you will run the
Switcher program to switch from MPLAB IDE v8 drivers to MPLAB X IDE drivers, which
are installed the first time your switch.
1. Plug your desired tool into USB connector on your personal computer.
2. Open the computer’s Device Manager window. For example, on a Windows XP
personal computer, right click on the My Computer icon and select “Properties”.
In the System Properties dialog, click the Hardware tab and then click the
Device Manager button.
3. Expand the “Microchip Tools” section to view the current driver for your tool. The
name should be of the form: Microchip Tool Name.
4. Go to the MPLAB X IDE install folder and find the Switcher folder, by default:
a) 32-bit OS: C:\Program Files\Microchip\MPLABX\Switcher
b) 64-bit OS: C:\Program Files (x86)\Microchip\MPLABX\Switcher
5. Under the Switcher folder, go to the folder for your operating system - 32Bit
or 64Bit.
6. Launch MPDDSwitch.exe (32-bit OS) or MPDDSwitch64.exe (64-bit OS).
7. If your MPLAB IDE v8 or MPLAB X IDE installation is not in the default directory,
click Advanced to specify the location of the driver files.

 2011-2012 Microchip Technology Inc. DS52027B-page 29

MPLAB® X IDE User’s Guide
8. To install or switch USB drivers:
a) Click to select the connected tool for which you wish to switch drivers under
“Tool Group and Action”.
b) Click the radio button for either “MPLAB 8” or “MPLAB X”.
c) Click Apply All. Switcher progress will be shown in the large text window.
This may take some time.
Note: If the tool(s) are not connected when Switcher is run, the driver(s) will
not be installed or switched for those particular tools.
9. If the GUI fails to install the drivers, check the paths to the driver files by clicking
Advanced. Run the Switcher again.
10. If the GUI still fails to install the drivers, you will need to install the drivers manu-
ally. For instructions and driver locations, see Section 2.3.2.5 “If You Need to
Manually Install the Drivers”.
11. Once the program/batch completes, view the name of the drivers in the Device
Manager window. It should say “Microchip WinUSB Device”.
Once your MPLAB X IDE drivers are installed, you can switch your drivers back and
forth between MPLAB IDE v8.xx and MPLAB X IDE.

2.3.2.4 IF MPLAB IDE V8.XX IS NOT INSTALLED ON YOUR SYSTEM

You do not need to do anything; the USB drivers will be preinstalled when MPLAB X
IDE is installed. Once you plug your tool into a computer USB port, a “New Hardware
Found” notification bubble should appear and install the drivers automatically. How-
ever, if the GUI fails to install the drivers, you will need to install the drivers manually.
For instructions and driver locations, see Section 2.3.2.5 “If You Need to Manually
Install the Drivers”.

2.3.2.5 IF YOU NEED TO MANUALLY INSTALL THE DRIVERS

If you need to install the drivers manually:
1. Open the Device Manager (under Control Panel). Look under “Microchip Tools”
for your tool or, if you cannot find it there, under “Other Devices” for “Unknown
Device”.
2. Right-click on your tool name or “Unknown Device” and select “Update Driver
Software”.
3. In the Update Driver Software dialog, select “Browse my computer for driver soft-
ware”.
Note: DO NOT select “Search automatically for updated driver software”.
This will install the wrong device driver. If you accidentally select this,
back out or exit and repeat these steps to install the correct driver.
4. Locate the correct device driver for your system. The default locations for the
device drivers are:
C:\Program Files\Microchip\MPLABX\Switcher\32Bit\winusb\
x86\MCHPWinUSBDevice.inf
or
C:\Program Files\Microchip\MPLABX\Switcher\64Bit\winusb\
amd64\MCHPWinUSBDevice.inf
For Windows 8 OS, the drivers are in either the x86_Windows8 or
amd64_Windows8 subfolder.
5. If a Windows Security dialog pops up, select “Install this driver software anyway”
to proceed to install the drivers.

DS52027B-page 30  2011-2012 Microchip Technology Inc.

 Before You Begin
2.3.2.6 TOOL COMMUNICATION ISSUES
1. If you are using a docking station or hub and have issues after plugging in the
tool, you may need to plug the tool directly into a USB port on your computer.
This is a known issue with the WinUSB driver.
2. If you need to reinstall a driver manually, you will need to point to the INF file in
the 32Bit or 64Bit folder. See Section 2.3.2.5 “If You Need to Manually
Install the Drivers” for details.

2.4 CONNECT TO A TARGET (FOR HARDWARE TOOLS)

For in-circuit debuggers and emulators, refer to the following to determine how to
connect your hardware tool to a target:
• the Development Tools Design Advisory
• the Header Specification (if you are using a header)
• your tool documentation
For dedicated programmers, refer to your tool documentation for connection
information.
If you are using a Microchip demonstration board, evaluation kit or reference design as
your target, please refer to the accompanying documentation for set up information.

2.5 INSTALL THE LANGUAGE TOOLS

When you install MPLAB X IDE, the following language tools are installed as well:
MPASM toolchain (ASM30 toolchain no longer included).
Currently there are several C compiler toolsuites (compiler, assembler, linker, etc.) that
can be used with MPLAB X IDE. Go to the Microchip web site:
http://www.microchip.com/xc
where you can find free compilers (Free, Evaluation) and full-featured, code-optimized
compilers (Standard, Pro).
To select a compiler toolsuite, consider the device you wish to use and then choose a
toolsuite that supports this device.
To install the compiler you want, download it and follow the instructions during the
download or within the zip file once downloaded.

 2011-2012 Microchip Technology Inc. DS52027B-page 31

MPLAB® X IDE User’s Guide

2.6 LAUNCH THE IDE

Double click on the MPLAB X IDE icon to launch the program.
MPLAB X IDE is built upon the NetBeans platform. If you are familiar with the NetBeans
IDE then the MPLAB X IDE desktop will look familiar.

FIGURE 2-2: MPLAB X IDE DESKTOP

On the Start Page, there are 3 tabs with links. The items on each tab are defined below.

DS52027B-page 32  2011-2012 Microchip Technology Inc.

 Before You Begin
TABLE 2-1: LEARN AND DISCOVER
Getting Started
Quick Start Get started quickly by creating and setting up a project.
MPLAB® IDE v8 Users – Install USBWin device drivers for your hardware tools.
IMPORTANT
Take a Tour Take a tour of MPLAB X IDE operation.
MPLAB® X IDE Limitations What is and is not currently supported on this version.
Dive In
Open Sample Project Open a functional project as an example.
Create New Project Create a new MPLAB X IDE project. It is recommended that you
view the “Quick Start” before creating your first project.
Import Legacy Project Import your existing MPLAB IDE v8 project. It is recommended
that you view the “Quick Start” before working with an imported
project.
New (Hex) Prebuilt Project Import the hex file from a prebuilt project for another tool.
Demos and Tutorials
Minute Videos View short videos explaining MPLAB X IDE operation.
Difference from MPLAB v8 View differences between MPLAB X IDE and MPLAB IDE v8.
All Tutorials View all available tutorials.
Community
Forums Go to the Microchip forums web page.
MPLAB X IDE Forum Register for the MPLAB X IDE forum.
MPLAB X IDE Wiki Open the MPLAB X IDE developer’s help center.

TABLE 2-2: MY MPLAB X IDE

Recent Projects
MyProject.c: List of recently opened projects.
Extend MPLAB
Selecting Simple or Full On initial start-up, MPLAB X IDE displays simple menus. For more
Featured Menus features, follow these instructions.
Install More Plug-Ins Open the plug-ins dialog.
Notes and Newsletters
ANxxxx, TBxxxx Featured application notes and technical briefs.
microSOLUTIONS Featured newsletters.
E-newsletter
All App Notes/ View all available.
Newsletters
References and Featured Links
Data Sheets, etc. Click a link to go to the item described.

 2011-2012 Microchip Technology Inc. DS52027B-page 33

MPLAB® X IDE User’s Guide
TABLE 2-3: WHAT’S NEW
Data Sheets and Errata
Data Sheet, Silicon List of featured data sheets and errata. To see a list of all these
Errata documents, all click “All Data Sheets” or “All Errata”.
Reference Manuals and Programming Spec
Family Reference Man- List of featured reference manuals and programming specifica-
ual, Device Program- tions. To see a list of all these documents, all click “All Reference
ming Spec Manuals” or “All Programming Specs”.
Recently Released Software
Source code List of recent software supporting Microchip device development.
To see a list of all these documents, all click “All Recently
Released Software”.
Product and Corporate News
New stuff, new news List of featured Microchip products and news. To see a list of all
these documents, all click “All News”.

DS52027B-page 34  2011-2012 Microchip Technology Inc.

 Before You Begin

2.7 LAUNCH MULTIPLE INSTANCES OF THE IDE

MPLAB X IDE requires each instance to have its own user directory. Therefore,
preferences set or plug-ins added to one instance will not be reflected in another.
In order to invoke multiple instances launch the IDE with the –-userdir option and
specify a directory.

2.7.1 Windows OS
Create a shortcut with the –-userdir option. For example:
1. Right click on the desktop and select New>Shortcut.
2. Browse to the installed MPLAB X IDE executable, by default at:
"C:\Program Files\Microchip\MPLABX\mplab_ide\bin\
mplab_ide.exe"
3. At the end of the line, enter:
--userdir "C:\Documents and Settings\MyFiles\
ApplicationData\.mplab_ide\dev\beta7Instance2"
4. Click OK.

2.7.2 Linux OS
The installed version run without any parameters (clicking on the desktop icon) will run
with a user directory of $(HOME)/.mplab_ide. To change the user directory, run the
$InstallationDir/mplab_ide/bin/mplab_ide shell script passing the argu-
ment --userid anydir. For example, to run MPLAB X IDE in two different instances:
$ /opt/microchip/mplabx/mplab_ide/bin/mplab_ide --userdir ~/.anydir1 &
$ /opt/microchip/mplabx/mplab_ide/bin/mplab_ide --userdir ~/.anydir2 &
You can create desktop icons that have the user ID embedded too.

2.7.3 Mac OS
Open a Shell window and type the following command line to execute your installation
of MPLAB X IDE (example: Beta 7.12) in the alternate user directory:
$/bin/sh /Applications/microchip/mplabx/712/mplab_ide.app/Contents/
Resources/mplab_ide/bin/mplab_ide --userdir "${HOME}/Library/
Application Support/mplab_ide/dev/beta7.12”

 2011-2012 Microchip Technology Inc. DS52027B-page 35

MPLAB® X IDE User’s Guide
NOTES:

DS52027B-page 36  2011-2012 Microchip Technology Inc.

 MPLAB® X IDE
USER’S GUIDE
Chapter 3. Tutorial
3.1 INTRODUCTION
This tutorial provides a guided example for working with an MPLAB X IDE project.
• Setting Up the Hardware and Software
- Tutorial Equipment
- Installation and Set Up
• Creating and Setting Up a Project
- Create a New Project
- View Changes to the Desktop
- View or Make Changes to Project Properties
- Set Options for Debugger, Programmer or Language Tools
- Set Language Tool Locations
- Add an Existing File to the Project
- Editor Usage
- Configuration Bits
• Running and Debugging Code
- Build a Project
- Run Code
- Debug Run Code
- Control Program Execution with Breakpoints
- Step Through Code
- Watch Symbol Values Change
- View Device Memory (Including Configuration Bits)
- Program a Device

 2011-2012 Microchip Technology Inc. DS52027B-page 37

MPLAB® X IDE User’s Guide

3.2 SETTING UP THE HARDWARE AND SOFTWARE

The following information discusses preparation to begin using the MPLAB X IDE.

3.2.1 Tutorial Equipment

The products used in this tutorial are:
Tool Web Page Order Number
MPLAB® X IDE http://www.microchip.com/mplabx Free
MPLAB® XC32 C http://www.microchip.com/xc SW006023-1
Compiler* (Standard Version)
MPLAB® REAL ICE™ http://www.microchip.com/realice DV244005
in-circuit emulator
Explorer 16 http://www.microchip.com/explorer16 DM240001
Development Board
PIC32MX360F512L PIM http://www.microchipdirect.com/product- MA320001
search.aspx?Keywords=MA320001
* You may acquire a free or evaluation edition of this compiler from the microchip website.
Download the compiler and, when installing, do not enter a license number.

3.2.2 Installation and Set Up

See Chapter 2. “Before You Begin” to install MPLAB X IDE, set up the emulator
(install USB drivers and properly connect to your target), and install the 32-bit language
tools. Then launch MPLAB X IDE and begin this tutorial.

DS52027B-page 38  2011-2012 Microchip Technology Inc.

 Tutorial

3.3 CREATING AND SETTING UP A PROJECT

The following information discusses setting up projects in MPLAB X IDE, which are
required to develop your application code.

3.3.1 Create a New Project

MPLAB X IDE is project-based, so you must set up a project to work on your
application.
New projects can be created by selecting either:
• Start Page, “Learn & Discover” tab, “Dive In”, “Create New Project”
• File>New Project (or Ctrl+Shift+N)
The New Project Wizard with launch to guide you through new project set up.

STEP 1
Step 1 asks you to choose a project category.
This is a NetBeans dialog. To work with Microchip products, choose “Microchip
Embedded”.
Secondly, choose a project type. For this tutorial choose “Stand-alone Project”.
Click Next> to move to the next dialog.

FIGURE 3-1: PROJECT WIZARD – CHOOSE PROJECT

 2011-2012 Microchip Technology Inc. DS52027B-page 39

MPLAB® X IDE User’s Guide
STEP 2
Step 2 opens on an MPLAB X IDE dialog that looks different than the dialog in Step 1.
Choose your device here, in this case PIC32MX360F512L, and then click Next>.

FIGURE 3-2: PROJECT WIZARD – SELECT DEVICE

STEP 3

Step 3 only appears if a header is available for your selected device. Since there is no
header for the PIC32MX360F512L device, MPLAB X IDE knows to skip this step.

DS52027B-page 40  2011-2012 Microchip Technology Inc.

 Tutorial
STEP 4
Step 4 selects the tool.
Tool support for the selected device is signified by the colored circles (lights) in front of
the tool name. If you cannot see the colors, mouse over a light to pop up text about
support.
Light Color Support
Green Full (Implemented and fully tested)
Yellow Beta (Implemented but not fully tested)
Red None

For some tools, there are two lights next to the tool name, where the first light is the
left-most light and the second light is to the right of the first.
Light No. Debug Tools Simulator
1 Debugger Support Core (Instruction Set) Support
2 Programmer Support Peripheral Support
For the hardware tools, you will notice that a serial number (SN) is specified below any
tool that is connected to your computer. This allows you to select from several
connected hardware tools.
Select your tool and then click Next>.

FIGURE 3-3: PROJECT WIZARD – SELECT TOOL

 2011-2012 Microchip Technology Inc. DS52027B-page 41

MPLAB® X IDE User’s Guide
STEP 5

Step 5 only appears if MPLAB REAL ICE in-circuit emulator is selected as the tool.
For the MPLAB REAL ICE in-circuit emulator, you may specify a plug-in board to use.
A plug-in board is the circuit board that is inserted into the emulator’s driver board slot.
Since the Explorer 16 board works with either the Standard or High-Speed Communi-
cations driver boards, leave the “Supported Plugin Board” as “None”.
Select your tool and then click Next>.

FIGURE 3-4: PROJECT WIZARD – SELECT PLUGIN

DS52027B-page 42  2011-2012 Microchip Technology Inc.

 Tutorial
STEP 6

Step 6 selects the language tool, either a C compiler or assembler. Again, the colored
circle (light) in front of the compiler name signifies the device support level. Mouse over
for text.
The version and installation location of a language tool is displayed beneath that tool.
This allows you to select from several installed language tools.
Select your tool and then click Next>.

FIGURE 3-5: PROJECT WIZARD – SELECT LANGUAGE TOOL

 2011-2012 Microchip Technology Inc. DS52027B-page 43

MPLAB® X IDE User’s Guide
STEP 7
Step 7 selects the project name, location and other project options.
Enter the project name MyProject.
By default, projects will be placed in:
• Windows XP – C:\Documents and Settings\UserName\MPLABXProject
• Windows 7 – C:\Users\UserName\MPLABXProjects
• Linux – /home/UserName/MPLABXProjects
• Mac – /Users/UserName/MPLABXProjects
If the Project Location does not point here, browse to the appropriate location.
Check “Set as main project” to make this your main project.
This tutorial was produced with the encoding set to ISO-8859-1 (Latin 1) so you do not
need to change this setting.
When you are done, select Finish to complete new project creation.

FIGURE 3-6: PROJECT WIZARD – SELECT PROJECT NAME AND

FOLDER

DS52027B-page 44  2011-2012 Microchip Technology Inc.

 Tutorial

3.3.2 View Changes to the Desktop

Once you have created your project, several panes will open in the IDE.
• File pane – A pane with four tabbed windows - Projects, Files, Classes and Ser-
vices windows. In this tutorial, we will focus on the Projects window, which dis-
plays the project tree with files grouped by category.
• Navigator pane – A pane that displays information on the file or project selected.
For a project, the project environment shows details about the project and for a
file, symbols and variables are shown.
• Editor pane – A pane for viewing and editing project files. The Start Page also is
visible here.
• Task pane – A pane that displays task output from building, debugging or running
an application.

FIGURE 3-7: MPLAB X IDE DESKTOP

If you double click on any file name in the File pane, the related file will open in the
Editor pane under a tab next to the Start Page. To close the tab, click on the “x” next to
the file name.
Right click on the project name in the File pane, Projects window, to view the pop-up
(context) menu. Do the same for the project’s subfolders.

 2011-2012 Microchip Technology Inc. DS52027B-page 45

MPLAB® X IDE User’s Guide

3.3.3 View or Make Changes to Project Properties

Once a project has been created, you can view or change the project properties in the
Project Properties dialog.
Access this dialog by either:
• right clicking on the project name in the Project window and selecting “Properties”.
• clicking on the project name in the Project window and then selecting File>Project
Properties.
Click the “Conf:[default]” category to reveal the general project configuration, such as
the project device, related debug/programmer tool, and language tool. Do not change
any of these items for this tutorial unless you have made a mistake in previous sections.
Then update in this dialog and click Apply.

FIGURE 3-8: PROJECT PROPERTIES DIALOG

DS52027B-page 46  2011-2012 Microchip Technology Inc.

 Tutorial

3.3.4 Set Options for Debugger, Programmer or Language Tools

Additionally, you set options for your tools in the Project Properties dialog.
To set up or change debugger/programmer tool options:
• Click on REAL ICE to see related set up options. For more on what these options
mean, see the emulator documentation.
Do not make any changes for this tutorial.

FIGURE 3-9: TOOL SET UP PAGE

 2011-2012 Microchip Technology Inc. DS52027B-page 47

MPLAB® X IDE User’s Guide
To set up or change language tool options:
• Click on your language tool to see related set up options. For more on what these
options mean, see your language tool documentation.
Do not make any changes for this tutorial.

FIGURE 3-10: LANGUAGE TOOL SET UP PAGE

DS52027B-page 48  2011-2012 Microchip Technology Inc.

 Tutorial

3.3.5 Set Language Tool Locations

To see what language tools are available to MPLAB X IDE and view or change their
paths:
• For Mac OS: Access the build tools from
mplab_ide>Preferences>Embedded>Build Tools from the main menu bar.
• For Other OSs: Access the build tools from Tools>Options>Embedded>Build
Tools.
The window should automatically populate with all installed toolchains. If you do not
see your tool listed, try the following:
• Scan for Build Tools – Scans the environment path and lists the language tools
installed on the computer.
• Add – Manually add the tool to the list by entering the path to the directory
containing the tool executable(s), i.e., base directory. Typically, this is the bin
subdirectory in the tool installation directory.
If you have more than one version of a compiler available, select one from the list.
Ensure that the XC32 toolchain is selected.

FIGURE 3-11: LANGUAGE TOOL (COMPILER) LOCATIONS

 2011-2012 Microchip Technology Inc. DS52027B-page 49

MPLAB® X IDE User’s Guide

3.3.6 Add an Existing File to the Project

For this tutorial, you will use existing example code:
• Go to the Explorer 16 Development Board web page on the Microchip web site:
http://www.microchip.com/explorer16
• Click “PIC32 Explorer 16 LED Example Application” to download the ZIP file
containing the example code.
• Once downloaded, unzip the project.
• Move the file led_message.c to the project directory (MyXProject.X).
Existing files can be added to a project by doing one of the following:
• Right clicking on the project in the Project/File window and selecting “Add Existing
Item”
• Right clicking on a logical folder (e.g., Source Files) in the Project/File window and
selecting “Add Existing Item”
When adding a file, you can choose whether to add it as:
• Auto – Let MPLAB X IDE decide how best to locate the file.
• Relative – Specify the file location relative to the project. (Recommended: Relative
paths will help portability when moving a project to another computer.)
• Absolute – Specify the file location by an absolute path.
The file will appear in the File pane under the project specified and a tab with the file’s
name will appear in the Editor pane.

FIGURE 3-12: LED_MESSAGE.C IN FILE PANE

DS52027B-page 50  2011-2012 Microchip Technology Inc.

 Tutorial
Code Listing for led_message.c:
/*********************************************************************
*
* Message via 8 LEDs
*
*********************************************************************
* FileName: led_message.c
* Dependencies:p32xxxx.h
*
*
* Processor: PIC32
*
* Complier: MPLAB C32
* MPLAB IDE v8.0+
* Company: Microchip Technology, Inc.
*
* Software License Agreement
*
* The software supplied herewith by Microchip Technology Incorporated
* (the “Company”) for its PIC32 Microcontroller is intended
* and supplied to you, the Company’s customer, for use solely and
* exclusively on Microchip PIC32 Microcontroller products.
* The software is owned by the Company and/or its supplier, and is
* protected under applicable copyright laws. All rights are reserved.
* Any use in violation of the foregoing restrictions may subject the
* user to criminal sanctions under applicable laws, as well as to
* civil liability for the breach of the terms and conditions of this
* license.
*
* THIS SOFTWARE IS PROVIDED IN AN “AS IS” CONDITION. NO WARRANTIES,
* WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED
* TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
* PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE COMPANY SHALL NOT,
* IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL OR
* CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER.
*
* $Id: led_message.c 5898 2007-10-23 19:39:48Z rajbhartin $
*
********************************************************************/

/*
** Message in a bottle
**
** Explorer16 version (long delays)
**
** Thanks to Lucio DiJasio for letting us use this example.
**
** Run this example on Explorer-16 board with PIC32MX PIM.
** Hold the board vertically from the PICtail connector size
** and wave the board back-and-forth to see message "HELLO" on LEDs
*/

#include <p32xxxx.h>

// Config settings
// POSCMOD = HS, FNOSC = PRIPLL, FWDTEN = OFF
// PLLIDIV = DIV_2, PLLMUL = MUL_16
// PBDIV = 8 (default)
// Main clock = 8MHz /2 * 16 = 64MHz
// Peripheral clock = 64MHz /8 = 8MHz

 2011-2012 Microchip Technology Inc. DS52027B-page 51

MPLAB® X IDE User’s Guide

// Configuration Bit settings

// SYSCLK = 64 MHz (8MHz Crystal/ FPLLIDIV * FPLLMUL / FPLLODIV)
// PBCLK = 8 MHz
// Primary Osc w/PLL (XT+,HS+,EC+PLL)
// WDT OFF
// Other options are don't care
//
#pragma config FPLLMUL = MUL_16, FPLLIDIV = DIV_2, FPLLODIV = DIV_1,
FWDTEN = OFF
#pragma config POSCMOD = HS, FNOSC = PRIPLL, FPBDIV = DIV_8

// 1. define timing constant

#define SHORT_DELAY (50*8)
#define LONG_DELAY(400*8)

// 2. declare and initialize an array with the message bitmap

char bitmap[30] = {
0xff,// H
0x08,
0x08,
0xff,
0,
0,
0xff,// E
0x89,
0x89,
0x81,
0,
0,
0xff,// L
0x80,
0x80,
0x80,
0,
0,
0xff,// L
0x80,
0x80,
0x80,
0,
0,
0x7e,// O
0x81,
0x81,
0x7e,
0,
0
};

// 3. the main program

main()
{
// disable JTAG port
DDPCONbits.JTAGEN = 0;

// 3.1 variable declarations

int i; // i will serve as the index

DS52027B-page 52  2011-2012 Microchip Technology Inc.

 Tutorial

// 3.2 initialization
TRISA = 0; // all PORTA as output
T1CON = 0x8030; // TMR1 on, prescale 1:256 PB

// 3.3 the main loop

while( 1)
{
// 3.3.1 display loop, hand moving to the right
for( i=0; i<30; i++)
{// 3.3.1.1 update the LEDs
PORTA = bitmap[i];

// 3.3.1.2 short pause

TMR1 = 0;
while ( TMR1 < SHORT_DELAY)
{
}
} // for i

// 3.3.2 long pause, hand moving back to the left

PORTA = 0; // turn LEDs off
TMR1 = 0;
while ( TMR1 < LONG_DELAY)
{
}
} // main loop
} // main

 2011-2012 Microchip Technology Inc. DS52027B-page 53

MPLAB® X IDE User’s Guide

3.3.7 Editor Usage

The sample code should not need to be edited. However, when you need to edit your
code, you will be using the NetBeans editor. General information on this editor is avail-
able from the table of contents under the NetBeans help topic IDE Basics>Basic File
Features. C compiler information regarding the editor is available from the table of con-
tents under the NetBeans help topic C/C++/Fortran Development>C/C++/Fortran Proj-
ect Basics>Navigating and Editing C/C++/Fortran Source Files. A list of features is
available under Chapter 7. “Editor”.
To use editor features, go to the:
• Edit menu (see Section 10.2.2 “Edit Menu”.)
• Editor toolbar located at the top of each file’s Editor window.
• Window right click (context) menu.

FIGURE 3-13: EDITOR TOOLBAR

3.3.8 Configuration Bits

In the sample code, Configuration bits are already set. For your own application, you
must set up the Configuration bits.
You must set Configuration bits in code. However, you can temporarily change Config-
uration bits during a debug session in the Configuration Bits window (Window>PIC
Memory Views>Configuration Bits). Then you may export the setting by right clicking in
the window and selecting “Generate Source Code to Output”. You can copy this code
from the Output window into your code.
For a summary of Configuration bits settings for different devices, see Chapter
14. “Configuration Settings Summary”.

DS52027B-page 54  2011-2012 Microchip Technology Inc.

 Tutorial

3.4 RUNNING AND DEBUGGING CODE

The following information discusses using the MPLAB X IDE to run or debug your code.

3.4.1 Build a Project

For MPLAB X IDE, it is not necessary to build the project first and then run or debug.
Building is part of the run and debug processes. For initial development or major
changes, however, you may want to make sure that the project builds before attempting
to run or debug.
To build a project:
• In the Project window, right click on the project name and select “Build”. You may
also select “Clean and Build” to remove intermediary files before building.
• Click on the “Build Project” or “Clean and Build Project” toolbar icon.

Build Icon

Clean and Build Icon

Build progress will be visible in the Output window (lower right hand corner of the desk-
top.) For this tutorial, the code should build successfully.

FIGURE 3-14: OUTPUT SUCCESSFUL BUILD

To view checksum information:

• Open the Dashboard window (Window>Dashboard) if it is not already open to see
the checksum after a build.

 2011-2012 Microchip Technology Inc. DS52027B-page 55

MPLAB® X IDE User’s Guide

3.4.2 Run Code

Once the code builds successfully, you can attempt to run the application. Click on the
“Make and Program Device Project” icon (or select Run>Run Project) to run your
program.

Make and Program Device Project Icon

The lights on the demo board should be flickering. Wave the board back and forth to
see the word, “Hello”.
Run progress will be visible in the Output window as well.
Use the Hold in Reset button to toggle between device Reset and running.

Hold in Reset Icon

You can add a “Run Project” icon to the toolbar if you wish
(View>Toolbars>Customize).

Run Icon

3.4.3 Debug Run Code

For this tutorial, the code used has been tested and runs. However, your own code may
need to be debugged as you develop your application.
To Debug Run the tutorial code, click on the “Debug Project” icon (or select
Debug>Debug Project or Debug>Step Into) to begin a debug session.

Debug Run Icon

Debug Run progress will be visible in the Output window.

To halt your application code:
• Click on the “Pause” icon (or select Debug>Pause) to halt your program execu-
tion.
To run your code again:
• Click on the “Continue” icon (or select Debug>Continue) to start your program
execution again.
To end execution of your code:
• Click on the “Finish Debugger Session” icon (or select Debug>Finish Debugger
Session) to end your program execution.
For more details on debugging C code projects, see the table of contents for the Net-
Beans help topic C/C++/Fortran Development>Debugging C/C++/Fortran Applications
with gdb.
The difference between Run and Debug Run will become apparent when working with
debug features, beginning with Section 3.4.4 “Control Program Execution with
Breakpoints”.

DS52027B-page 56  2011-2012 Microchip Technology Inc.

 Tutorial

3.4.4 Control Program Execution with Breakpoints

When debugging code, it can be useful to suspend execution at a specific location in
code so that variable values can be examined. To do this, use breakpoints.
Set a breakpoint on the following line of code:
PORTA = bitmap[i];
To set a breakpoint on a line do one of the following:
• Click the left margin of the line in the Source Editor
• Press Ctrl-F8

FIGURE 3-15: BREAKPOINT SET IN CODE

Debug Run the tutorial program again. The program will halt at the breakpoint. Hover
over the bitmap[] variable to see its values.

FIGURE 3-16: PROGRAM EXECUTION HALTED AT BREAKPOINT

 2011-2012 Microchip Technology Inc. DS52027B-page 57

MPLAB® X IDE User’s Guide
To clear the breakpoint do one of the following:
• Repeat the step to set a breakpoint
• Select Debug>Toggle Breakpoint
For more on breakpoints, see the table of contents for the NetBeans help topics under
C/C++/Fortran Development>Debugging C/C++/Fortran Applications with gdb>Setting
C/C++/Fortran Breakpoints.

3.4.5 Step Through Code

Use one of the stepping functions on the Debug menu and Debug toolbar to move
through code either from the beginning of code or after a breakpoint halt. Examine
changes in variable values (see next section) or determine if the program flow is
correct.
There are several ways to step through code:
• Step Over – Executes one source line of a program. If the line is a function call,
executes the entire function then stops.
• Step Into – Executes one source line of a program. If the line is a function call,
executes the program up to the function’s first statement and stops.
• Step Out – Executes one source line of a program. If the line is a function call,
executes the functions and returns control to the caller.
• Run to Cursor – Runs the current project to the cursor’s location in the file and
stop program execution.
• Animate – Execute single steps while running, updating the values of the registers
as it runs. Animate is slower than Run, but allows you to view changing register
values in the Special Function Register window or in the Watch window.
For more on stepping, see the table of contents for the NetBeans help topics under
C/C++/Fortran Development>Debugging C/C++/Fortran Applications with
gdb>C/C++/Fortran Debugging Sessions>Stepping Through Your C/C++/Fortran
Program.

DS52027B-page 58  2011-2012 Microchip Technology Inc.

 Tutorial

3.4.6 Watch Symbol Values Change

Watch the values of symbols that you select change in the Watches window. Determin-
ing if these values are as expected during program execution will help you to debug
your code.
To create a new watch:
1. Select Debug>New Watch. The New Watch dialog will open (Figure 3-17).
2. Enter a Watch expression, in this case PORTA, and then click OK. The Watches
window will now appear on the desktop with the symbol.
OR
1. Right click on PORTA in code and select “New Watch”.
2. The Watches window will open with PORTA in it.
OR
1. Select Window>Debugging>Watches.
2. Drag and drop PORTA from the editor window into the Watches window.

FIGURE 3-17: WATCHES WINDOW WITH SYMBOL

To view symbol changes:

1. Debug Run and then Pause your program.
2. Click the Watches tab to view the window and see the symbol value. (Red text
means a change.)
For more on watches, see the table of contents for the NetBeans help topics under
C/C++/Fortran Development>Debugging C/C++/Fortran Applications with
gdb>Viewing C/C++/Fortran Program Information>Creating a C/C++/Fortran Watch.

 2011-2012 Microchip Technology Inc. DS52027B-page 59

MPLAB® X IDE User’s Guide

3.4.7 View Device Memory (Including Configuration Bits)

MPLAB X IDE has flexible, abstracted memory windows that provide a customizable
view of differing types of device memory. From a Memory window, you select the type
of memory and memory format in drop-down boxes.
Begin by viewing Flash memory:
1. Select Window>PIC Memory Views>Execution Memory.
2. The Execution Memory window will open showing the last halt location.

FIGURE 3-18: MEMORY WINDOW CONTENT

Change the memory view by:

• Selecting another window from the Window>PIC Memory Views list.
• Using the drop-down “Memory” menu on the window.
To set Memory window options:
Right clicking in the Memory window will pop up a menu with various options such as
display options, fill memory, table import/export and output to file. For more information
on this menu, see Section 11.2.4.1 “Memory Window Menu”.
To refresh the Flash Memory window:
1. Halt your program (Finish Debugger Session).
2. Click on the icon named “Read Device Memory”.

Read Device Memory Icon

DS52027B-page 60  2011-2012 Microchip Technology Inc.

 Tutorial

3.4.8 Program a Device

Once your code is debugged, you can program it onto a target device. There are two
ways to do this:
• Click Run: The project is built (if necessary) and device is programmed. The pro-
gram will immediately begin execution on completion of programming.
• Click Make and Program Device: The project is built (if necessary) and device is
programmed. The program will NOT immediately begin execution on completion
of programming. You will need to disconnect the hardware tool from the target
board before the application will run.
Other programming-related functions are:
• Hold in Reset: Toggle the device between Reset and Run.
• Read Device Memory: Transfer what is in target memory to MPLAB X IDE.
Programming-related icons are:

Run Icon

Hold In Reset Icon

Make and Program Device Icon

Read Device Memory Icon

Note: Not all programming functions are in the MPLAB X IDE. For additional pro-
gramming support, see the MPLAB IPE included with the MPLAB X IDE
installation.

 2011-2012 Microchip Technology Inc. DS52027B-page 61

MPLAB® X IDE User’s Guide
NOTES:

DS52027B-page 62  2011-2012 Microchip Technology Inc.

 MPLAB® X IDE
USER’S GUIDE
Chapter 4. Basic Tasks
4.1 INTRODUCTION
This chapter provides a step by step guide for working with MPLAB X IDE projects, as
summarized in Working with MPLAB X IDE Projects.

4.2 WORKING WITH MPLAB X IDE PROJECTS

The following steps demonstrate how to work with projects in MPLAB X IDE
1. Before You Begin, install MPLAB X IDE, set up any hardware tools (install
USB drivers and properly connect to your target) and install language tools
for your selected device. Then launch MPLAB X IDE and begin this tutorial.
Preliminaries

1. Create a New Project by using the New Project wizard. Then View Changes
to the Desktop.
Create and Build a 2. View or Make Changes to Project Properties in the Project Properties
Project dialog. Also Set Options for Debugger, Programmer or Language Tools in
the same dialog.
3. Set Language Tool Locations and Set Other Tool Options in the Tools
Options dialog.
4. Create a New File to add to your project or Add Existing Files to a Project.
Enter or edit your application code to the File window.
5. Discover other features for Editor Usage.
6. Add and Set Up Library and Object Files.
7. Set File Properties to keep or exclude individual files from the build.
8. Set Build Properties for pre- and post-build steps and loading an alternative
hex file on build.
9. Build a Project.

1. Run Code with the Run menu.

2. Debug Run Code with the Debug menu.
Execute Code

1. Control Program Execution with Breakpoints. Set breakpoints in-line or via

the Breakpoint window.
Debug Code 2. Step Through Code as the program executes.
3. Watch Symbol Values Change in the Watches and Variables windows.
4. View/Change Device Memory (including Configuration Bits). Memory types
are dependent on the device selected.
5. Use View the Call Stack to navigate function calls.

1. Program a Device using simple toolbar buttons.

Program a Device

 2011-2012 Microchip Technology Inc. DS52027B-page 63

MPLAB® X IDE User’s Guide

4.3 CREATE A NEW PROJECT

MPLAB X IDE is project-based, so you must set up a project to work on your
application.
New projects can be created by selecting either of the following starting points:
• Start Page, “Learn and Discover” tab, “Dive In”, “Create New Project”
• File>New Project (or Ctrl+Shift+N)
The New Project wizard with launch to guide you through new project set up.

4.3.1 Step 1: Choose Project

Step 1 will first ask you to choose a project category. In most cases you will choose a
project type from “Microchip Embedded”:
• Standalone Project – Create a new C and/or assembly code project. This type of
project is shown in this section.
• Existing MPLAB IDE v8 Project – Convert your existing MPLAB IDE v8 project
into an MPLAB X IDE project. For details see Section 5.3 “Import MPLAB Leg-
acy Project”.
• Prebuilt (Hex, Loadable Image) Project – Load an existing project image into
MPLAB X IDE. For details, see Section 5.4 “Prebuilt Projects”.
• Library Project – Create a new C and/or assembly code project that will build into
a library instead of executable hex file. For details, see Section 5.6 “Library
Projects”.
Other options are:
• Other Embedded Projects – Projects from other venders.
• Sample Projects – Includes ready-to-use projects for different device families and
project templates for different device families.
Once you have made your selections, click Next> to move to the next dialog.

FIGURE 4-1: PROJECT WIZARD – CHOOSE PROJECT

DS52027B-page 64  2011-2012 Microchip Technology Inc.

 Basic Tasks

4.3.2 Step 2: Select Device

Step 2 is an MPLAB X IDE dialog and looks different from the Step 1 dialog. Select the
device you will be using in your application from the “Device” drop-down list. To narrow
your selection list, chose a Family first. Click Next>.

FIGURE 4-2: PROJECT WIZARD – SELECT DEVICE

 2011-2012 Microchip Technology Inc. DS52027B-page 65

MPLAB® X IDE User’s Guide

4.3.3 Step 3: Select Header

Step 3 will appear if a header is available for your selected device. To determine if a
header is required for debug or if your device has on-board debug circuitry, consult the
“Processor Extension Pak and Header Specification” (DS51292 or online help). Then
choose whether or not to use a header. Click Next> when done.

Note: You can select a header later (if one is available) using the Project Proper-
ties window.

FIGURE 4-3: PROJECT WIZARD – SELECT HEADER

DS52027B-page 66  2011-2012 Microchip Technology Inc.

 Basic Tasks

4.3.4 Step 4: Select Tool

Step 4 involves selecting the tool.
Tool support for the selected device is signified by the colored circles (lights) in front of
the tool name. If you cannot see the colors, mouse over a light to pop up text about
support.
Light Color Support
Green Full (Implemented and fully tested)
Yellow Beta (Implemented but not fully tested)
Red None

For some tools, there are two lights next to the tool name, where the first light is the
left-most light and the second light is to the right of the first.
Light No. Debug Tools Simulator
1 Debugger Support Core (Instruction Set) Support
2 Programmer Support Peripheral Support
For the hardware tools, you will notice that a serial number (SN) is specified below any
tool that is connected to your computer. This allows you to select from several
connected hardware tools.
Select your tool and then click Next>.

FIGURE 4-4: PROJECT WIZARD – SELECT TOOL

 2011-2012 Microchip Technology Inc. DS52027B-page 67

MPLAB® X IDE User’s Guide

4.3.5 Step 5: Select Plug-In Board

For the MPLAB REAL ICE in-circuit emulator, you may specify a plug-in board to use.
A plug-in board is the circuit board that is inserted into the emulator’s driver board slot.

TABLE 4-1: EMULATOR PLUGIN BOARDS

Option Selection Related Board
None Standard Communications driver board
None High-Speed Communications driver board
JTAG Driver Board* JTAG Adapter board
Power Monitor Board* Power Monitor board (also inserts into logic probe connector)
* These boards coming soon.

Select your tool and then click Next>.

FIGURE 4-5: PROJECT WIZARD – SELECT PLUGIN

DS52027B-page 68  2011-2012 Microchip Technology Inc.

 Basic Tasks

4.3.6 Step 6: Select Compiler

Step 6 involves selecting the language tool, either a C compiler or assembler. Again,
the colored circle (light) in front of the compiler name signifies the device support level.
Mouse over for text.

Note: If you do not see your language tool listed, look under Tools>Options
(mplab_ide>Preferences for Mac OSX), Embedded button, Build Tools
tab, to ensure MPLAB X IDE can find the tool. If your tool is listed, then your
project device may not be supported by your tool. Consider selecting or
installing another language tool that supports the device.

TABLE 4-2: MICROCHIP LANGUAGE TOOLS

Toolchain Full Name
8-Bit Device Language Tools
MPASM MPASM Assembler, MPLINK Object Linker and Utilities
C18 MPLAB C Compiler for PIC18 MCUs
HI-TECH PICC HI-TECH C Compiler for PIC10/12/16 MCUs*
HI-TECH PICC18 HI-TECH C Compiler for PIC18 MCUs*
XC8 MPLAB XC8 C Compiler*
16-Bit Device Language Tools
ASM30 MPLAB Assembler, Object Linker and Utilities for PIC24 MCUs and
dsPIC DSCs**
C30 MPLAB C Compiler for PIC24 MCUs and dsPIC DSCs*
C24 MPLAB C Compiler for PIC24 MCUs* (subset of C30)
dsPIC MPLAB C Compiler for dsPIC DSCs* (subset of C30)
HI-TECH DSPICC HI-TECH C Compiler for PIC24 MCUs and dsPIC DSCs*
XC16 MPLAB XC16 C Compiler*
32-Bit Device Language Tools
C32 MPLAB C Compiler for PIC32 MCUs*
HI-TECH PICC32 HI-TECH C Compiler for PIC32 MCUs*
XC32 MPLAB XC32 C Compiler*
* Includes an assembler, linker and utilities.
** No longer included with MPLAB X IDE in v1.30. Use the assembler that comes with one of
the compilers.

For more on each language tool, consult the language tool documentation.
For third party language toolchains (CCS, etc.), see the “Readme for Third Party
Tools.htm” file on the Start Page, “Release Notes and Support Documentation”.

 2011-2012 Microchip Technology Inc. DS52027B-page 69

MPLAB® X IDE User’s Guide
Select your tool and then click Next>.

FIGURE 4-6: PROJECT WIZARD – SELECT LANGUAGE TOOL

DS52027B-page 70  2011-2012 Microchip Technology Inc.

 Basic Tasks

4.3.7 Step 7: Select Project Name and Folder

Step 7 involves selecting the project name, location and other project features. When
you are done, select Finish to complete new project creation.
Project Name, Location and Folder
Enter the project name. By default, the name will be appended with .X. This is not
required and simply a convention. You can delete this is you wish in the “Project Folder”
text box.
Browse to a folder location. You can create a new project folder if you need one. By
default, projects will be placed in:
• Windows XP – C:\Documents and Settings\UserName\MPLABXProject
• Windows 7 – C:\Users\UserName\MPLABXProjects
• Linux – /home/UserName/MPLABXProjects
• Mac – /Users/UserName/MPLABXProjects
However, you may choose to put them in your own location.
Main Project
Check “Set as main project” to specify this project as your main project.
Encoding
Select the encoding for the project. The default is ISO-8859-1 (Latin 1) character set.
This selection will specify the code syntax coloring, which can be edited under
Tools>Options (mplab_ide>Preferences for Mac OSX), Fonts and Colors button,
Syntax tab.

FIGURE 4-7: PROJECT WIZARD – SELECT PROJECT NAME AND

FOLDER

 2011-2012 Microchip Technology Inc. DS52027B-page 71

MPLAB® X IDE User’s Guide

4.4 VIEW CHANGES TO THE DESKTOP

Once you have created your project, several panes will open in the IDE.
• File pane – pane with four tabbed windows:
- The Projects window displays the project tree with files grouped by category.
- The Files window displays the project files according to the folder organization
on your computer.
- The Classes window displays any classes and their functions, variables and
constants in the code. Double click on an item to see its declaration.
- The Services window displays any services available to use for code develop-
ment.
• Navigator pane – displays information on the symbols and variables in the file
selected in the File pane.
• Editor pane – for viewing and editing project files. The Start Page also is visible
here.
• Task pane – displays task output from building, debugging, or running an
application.

FIGURE 4-8: MPLAB X IDE DESKTOP

DS52027B-page 72  2011-2012 Microchip Technology Inc.

 Basic Tasks
If you double click on any file name in the File pane, the related file will open in the Edi-
tor pane under a tab next to the Start Page. To close the tab, click on the “x” next to the
file name.
Right click on the project name in the File pane, Projects window, to view the pop-up
(context) menu. Do the same for the project’s subfolders.

4.5 VIEW OR MAKE CHANGES TO PROJECT PROPERTIES

Once a project has been created, you can view or change the project properties in the
Project Properties dialog. Access this dialog by either:
• right clicking on the project name in the Project window and selecting “Properties”.
• clicking on the project name in the Project window and then selecting File>Project
Properties.
Click the “Conf: [default]” category to reveal the general project configuration, such as
the project device, related debug/programmer tool, and language tool. To change any
of these items, refer to steps 4 and 5 of Section 4.3 “Create a New Project”.

FIGURE 4-9: PROJECT PROPERTIES DIALOG

 2011-2012 Microchip Technology Inc. DS52027B-page 73

MPLAB® X IDE User’s Guide

4.6 SET OPTIONS FOR DEBUGGER, PROGRAMMER OR LANGUAGE TOOLS

Additionally, you set options for your tools in the Project Properties dialog.
To set up or change debugger/programmer tool options:
Click on your hardware tool or simulator (beneath Conf:[default]) to see related set up
options. For more on what these options mean, see your tool documentation.

FIGURE 4-10: TOOL SET UP PAGE

DS52027B-page 74  2011-2012 Microchip Technology Inc.

 Basic Tasks
To set up or change language tool options:
Click on your language tool to see related set up options. For more on what these
options mean, see your language tool documentation.
See the table of contents for the NetBeans help topic C/C++/Fortran
Development>Working with C/C++/Fortran Projects>Setting Project Properties for
additional help.

FIGURE 4-11: LANGUAGE TOOL SET UP PAGE

 2011-2012 Microchip Technology Inc. DS52027B-page 75

MPLAB® X IDE User’s Guide

4.7 SET LANGUAGE TOOL LOCATIONS

To see what language tools are available to MPLAB X IDE and view or change their
paths:
• For Mac OSX: Access the build tools from
mplab_ide>Preferences>Embedded>Build Tools from the main menu bar.
• For Other OS: Access the build tools from Tools>Options>Embedded>Build
Tools.
The window should automatically populate with all installed toolchains. If you do not
see your tool listed, try the following:
• Scan for Build Tools – Scan the environment path and list the language tools
installed on the computer.
• Add – Manually add the tool to the list by entering the path to the directory
containing the tool executable(s), i.e., base directory. Typically, this is the bin
subdirectory in the tool installation directory.
If you have more than one version of a compiler available, select one from the list.
To change the path of a tool, enter the new path or browse for it.

FIGURE 4-12: LANGUAGE TOOL (COMPILER) LOCATIONS

DS52027B-page 76  2011-2012 Microchip Technology Inc.

 Basic Tasks

4.8 SET OTHER TOOL OPTIONS

In addition to the build paths, you may set up other options. Select from the following
tabs in the Options window, Embedded category:
• Project Options – Set project-related options, such as make options and whether
paths are defaulted to relative or absolute (Section 11.2.8.2 “Project Options
tab”).
• Generic Settings – Set up the log file and other project features
(Section 11.2.8.3 “Generic Settings tab”).
• Suppressible Messages – Select messages to be suppressed
(Section 11.2.8.4 “Suppressible Messages”)
• Other – Edit the lists of accepted file extensions for C source files and header files
(Section 11.2.8.5 “Other tab”).

4.9 CREATE A NEW FILE

New files can be created by doing one of the following:
• Selecting File>New File (or Ctrl+N)
• Right clicking on the project in the Project/File window and selecting New>Other
• Right clicking on a logical folder (e.g., Source Files) in the Project/File window and
selecting New>Other
A New File Wizard with launch to guide you through new file set up.
Step 1. Choose File Type: Choose the file category by expanding “Microchip Embed-
ded” to find an appropriate selection. Then select a file type.

FIGURE 4-13: FILE WIZARD – CHOOSE CATEGORY AND TYPE

 2011-2012 Microchip Technology Inc. DS52027B-page 77

MPLAB® X IDE User’s Guide
Step 2. Name and Location: Name the file and place it in the project folder.

FIGURE 4-14: FILE WIZARD – CHOOSE ASSOCIATED PROJECT

The file will appear in the File pane under the project specified and a tab with the file’s
name will appear in the Editor pane. Enter your file content under this tab. The text in
the file will have syntax color based on its file type.

FIGURE 4-15: NEW FILE – MYFILE.C

DS52027B-page 78  2011-2012 Microchip Technology Inc.

 Basic Tasks

4.10 ADD EXISTING FILES TO A PROJECT

Existing files can be added to a project by doing one of the following:
• Right clicking on the project in the Project/File window and selecting “Add Existing
Item”
• Right clicking on a logical folder (e.g., Source Files) in the Project/File window and
selecting “Add Existing Item”

4.10.1 Files in Project Folder

When adding a file, you can choose whether to add it as:
• Auto – Let MPLAB X IDE decide how best to locate the file.
• Relative – Specify the file location relative to the project. (Most portable project.)
• Absolute – Specify the file location by an absolute path.
The file will appear in the File pane under the project specified and a tab with the file’s
name will appear in the Editor pane.

4.10.2 Files Outside of Project Folder

When adding a source file that is not in the project folder, add the file as “Relative”. This
will create an external folder (_ext) so the project can find the file when building.
To make use of navigation features such as //TODO and file context menus, you must
tell the project where the files are located. To do this:
1. In the Projects window, click on the project name and select “Properties”.
2. Under “Categories”, click “General”.
3. Next to “Source Folders”, click Add.
4. Browse to the path to the external file(s) you have added to the project. Select
Select.
5. Click Apply or OK. Then rebuild the project.
When you import an MPLAB IDE v8 project, the source files are a not in the project
folder. Use File>Import>MPLAB IDE v8 Project to automatically import the files.

 2011-2012 Microchip Technology Inc. DS52027B-page 79

MPLAB® X IDE User’s Guide

4.11 EDITOR USAGE

To create new code or change existing code, use the NetBeans editor. General infor-
mation on this editor is available from the table of contents under the NetBeans help
topic IDE Basics>Basic File Features. C compiler information regarding the editor is
available from the table of contents under the NetBeans help topic C/C++/Fortran
Development>C/C++/Fortran Project Basics>Navigating and Editing C/C++/Fortran
Source Files. A list of features is available under Chapter 7. “Editor”.
To use editor features, go to the:
• Edit menu (see Section 10.2.2 “Edit Menu”.)
• Editor toolbar located at the top of each file’s Editor window.

FIGURE 4-16: EDITOR TOOLBAR

• Window right click (context) menu.

To set editor properties:
1. Select Tools>Options (mplab_ide>Preferences for Mac OSX) to open the
Options dialog.
2. Click on the Editor button. Then click on a tab to set up a editor features.
3. Click on the Fonts and Colors button. Then click on a tab to set up color options.
To navigate through files and format your code:
1. Select items from the Navigate menu to navigate inside and outside of files.
2. Select items from the Source menu to format, comment, and auto-complete
code.
To use code folding:
For details on code folding, see Section 7.5 “Code Folding”.

DS52027B-page 80  2011-2012 Microchip Technology Inc.

 Basic Tasks

4.12 ADD AND SET UP LIBRARY AND OBJECT FILES

You can reference library files to be used by the linker in the following locations:
• the Libraries folder in the Projects window
• the Project Properties dialog
Additional library file set up may be done in the language tool librarian.

4.12.1 Libraries Folder

In the Projects window, right click on the Libraries folder to see these options:
• Add Library Project
Make a project that produces a library as its output required for your project, i.e.,
establish a dependency. For more on this, see the table of contents for the Net-
Beans help topic C/C++/Fortran Development>C/C++/Fortran Project
Basics>Building C/C++/Fortran Projects>Creating Dependencies Between
C/C++/Fortran Projects.
• Add Library/Object File
Add an existing library file or pre-built (object) file to the project.
• Properties
Open the project’s Properties window to select additional options (see next
section).

4.12.2 Project Properties Window: Libraries Category

Open the Project Properties window and click on the “Libraries” category (Figure 4-17).
Any files added to the Libraries folder in the Projects window will be visible here. You
may add additional files and manage these files using the buttons on the right.
The order of the files here determines their link order.

FIGURE 4-17: MANAGE LIBRARY/OBJECT FILES AND SET UP LINK

ORDER

 2011-2012 Microchip Technology Inc. DS52027B-page 81

MPLAB® X IDE User’s Guide

4.12.3 Project Properties Window: Librarian Category

Open the Project Properties window and click on the librarian under your language tool
category (Figure 4-18). Consult your language tool documentation to determine the
executable name of your librarian.
In the left pane, click on the name of the linker and then in the right pane, select the
option “Libraries”. Choose library options from this list.

FIGURE 4-18: SET UP LIBRARIES OPTIONS IN THE LIBRARIAN

DS52027B-page 82  2011-2012 Microchip Technology Inc.

 Basic Tasks

4.13 SET FILE PROPERTIES

A project file can be built differently from other files in the project using the File Proper-
ties dialog. Access this dialog by right clicking on the file name in the Project window
and selecting “Properties”. Select to exclude the file from the project build or override
the project build options with the ones selected here. To override build options, check
the checkbox and then click “Apply” to see selection options appear under “Catego-
ries”.

FIGURE 4-19: FILE PROPERTIES

 2011-2012 Microchip Technology Inc. DS52027B-page 83

MPLAB® X IDE User’s Guide

4.14 SET BUILD PROPERTIES

Before building the project, you may want to set up additional build properties:

TABLE 4-3: BUILD ALTERNATIVE OPTIONS

Item Description
Execute this line before Pre-build/make steps. Select the macro from the list and click
the build Insert Macro. Additional options may be available, depending on
the compiler used.
Execute this line after the Post-build/make steps. Select the macro from the list and click
build Insert Macro. Additional options may be available, depending on
the compiler used.
Insert checksum in user If supported by the device, check to use the checksum number
ID memory generated after a build as the user ID.
Normalize hex file Check to place hex file line addresses in incremental order using
hexmate, a HI-TECH utility. For more information on hexmate, see
“manual.pdf” in the docs folder of the installed HI-TECH compiler.
Uncheck to leave in linker order.

FIGURE 4-20: MAKE OPTIONS BUILD PROPERTIES

DS52027B-page 84  2011-2012 Microchip Technology Inc.

 Basic Tasks

4.15 BUILD A PROJECT

For MPLAB X IDE, it is not necessary to build the project first and then run or debug.
Building is part of the run and debug processes. For initial development or major
changes, however, you may want to make sure that the project builds before attempting
to run or debug.
To build a project:
• In the Project window, right click on the project name and select “Build”. You may
also select “Clean and Build” to remove intermediary files before building.
• Click on the “Build Project” or “Clean and Build Project” toolbar icon.
Build progress will be visible in the Output window.
Available build functions are:

TABLE 4-4: BUILD OPTIONS ON TOOLBAR BUTTONS

Button
Function Description
Icon
Build Project Make all the files in the project.
Build for Debugging Make all the files in the project and add a
debug executive to the built image.
Clean and Build Remove previous build files and make all
the files in the project.
Clean and Build for Debugging Remove previous build files and make all
the files in the project. Add a debug execu-
tive to the built image.
To view errors in the Output window:
1. Right click in the Output window and select “Filter”.
2. In the Filter dialog, check “Match” and enter “: error” to show only errors in the
Output window that stopped the build.
3. Toggle the filter on and off using <Ctrl>-<G>.
See you language tool documentation for a discussion of errors.
To view checksum information:
• Open the Dashboard window (see Section 5.15 “View the Dashboard Display”)
to see the checksum after a build.
For more information on building your project, also see the table of contents for the Net-
Beans help topic C/C++/Fortran Development>C/C++/Fortran Project Basics>Building
C/C++/Fortran Projects.

 2011-2012 Microchip Technology Inc. DS52027B-page 85

MPLAB® X IDE User’s Guide

4.16 RUN CODE

Once the code builds successfully, you can attempt to run the application.

4.16.1 How Run Works

On clicking the “Run Project” toolbar button:
1. A build if the make process determines it is necessary.
2. For in-circuit debuggers/emulators and programmers, the target device will auto-
matically be programmed with the image (no debug executive) and the device
will then be released to run, i.e., no breakpoints or other debug features will be
enabled. To hold a device in Reset after programming, click “Hold in Reset”
instead of “Run Project”.

Hold in Reset

3. For simulators, the application will simply execute with no debugging capability.
Run progress will be visible in the Output window.
MPLAB X IDE operation connects to the hardware tool at runtime (Run or Debug Run).
To always be connected to the hardware tool (like MPLAB IDE v8), see Tools>Options
(mplab_ide>Preferences for Mac OSX), Embedded button, Generic Settings tab,
“Maintain active connection to hardware tool” checkbox.
For more on programming a device, see Section 4.24 “Program a Device”.

4.16.2 Running Your Application Code

1. In the Project window, select your project or make it the main project (right click
on the project and select “Set as main”.)
2. Click on the “Make and Program Device” icon (or select Run>Run Project) to run
your program.

Make and Program Device

Run progress will be visible in the Output window.

DS52027B-page 86  2011-2012 Microchip Technology Inc.

 Basic Tasks

4.17 DEBUG RUN CODE

If your code does not run successfully, you will need to debug it. Running the code in
debug mode is called a Debug Run.

4.17.1 How Debug Run Works

On clicking the “Debug Project” toolbar button:
1. A build will occur if the make process determines it is necessary.
2. For in-circuit debuggers/emulators, the target device or header will automatically
be programmed with the image (including the debug executive) and a debug ses-
sion will be started.
3. For simulators, a debug session will be started.
Debug Run progress will be visible in the Output window.
You will need to be in a debug session (debug mode) to activate many debugging fea-
tures. For example, to view variable values in watch or memory windows.
MPLAB X IDE operation connects to the hardware tool at runtime (Run or Debug Run).
To always be connected to the hardware tool (like MPLAB IDE v8), see Tools>Options
(mplab_ide>Preferences for Mac OSX), Embedded button, Generic Settings tab,
“Maintain active connection to hardware tool” checkbox.
For some applications you may need to break down the debug steps for independent
execution. To do this, use the steps under Debug>Discrete Debugger Operation.

4.17.2 Debugging Your Application Code

To debug your application code:
1. In the Project window, select your project or make it the main project (right click
on the project and select “Set as main”.)
2. Click on the “Debug Project” icon (or select Debug>Debug Project or
Debug>Step Into) to begin a Debug Run.

Debug Project

To halt your application code:

• Click on the “Pause” icon (or select Debug>Pause) to halt your program execu-
tion.
To run your code again:
• Click on the “Continue” icon (or select Debug>Continue) to start your program
execution again.
To end execution of your code:
• Click on the “Finish Debugger Session” icon (or select Debug>Finish Debugger
Session) to end your program execution.
The difference between Run and Debug Run will become apparent when working with
debug features, beginning with Section 4.18 “Control Program Execution with
Breakpoints”.
To launch the debugger:
If you code is build for debugging and you simply want to launch the debug tool, you
can do so by selecting the down arrow next to the “Debug Project” icon and selecting
“Launch Debugger”.

 2011-2012 Microchip Technology Inc. DS52027B-page 87

MPLAB® X IDE User’s Guide

4.18 CONTROL PROGRAM EXECUTION WITH BREAKPOINTS

When debugging code, it can be useful to suspend execution at a specific location in
code so that variable values can be examined. To do this, use breakpoints.
For more on breakpoints, see the table of contents for the NetBeans help topics under
C/C++/Fortran Development>Debugging C/C++/Fortran Applications with gdb>Setting
C/C++/Fortran Breakpoints.

FIGURE 4-21: BREAKPOINT AND BREAKPOINTS WINDOW

4.18.1 Set/Clear a Simple Breakpoint

To set a breakpoint on a line do one of the following:
• Click the left margin of the line in the Source Editor
• Press Ctrl+F8
To clear the breakpoint do one of the following:
• Repeat the step to set a breakpoint
• Select Debug>Toggle Breakpoint.

DS52027B-page 88  2011-2012 Microchip Technology Inc.

 Basic Tasks

4.18.2 Set Breakpoints with the Breakpoint Dialog

To set a breakpoint with the New Breakpoint dialog:
1. Select Debug>New Breakpoint.
2. Select the breakpoint type and other options in the New Breakpoint dialog.

4.18.3 Set/Clear Breakpoints in the Breakpoints Window

To view and toggle the breakpoint in the Breakpoints window:
1. Select Window>Debugging>Breakpoints.
2. Toggle the breakpoint by checking/unchecking the checkbox.
To set a breakpoint with the New Breakpoint dialog:
1. Click on the icon in the top left of the window.

4.18.4 Set a Breakpoint Sequence (Device Dependent)

A breakpoint sequence is a list of breakpoints that execute but do not halt until the last
breakpoint is executed. Sequenced breakpoints can be useful when there is more than
one execution path leading to a certain instruction and you only want to exercise one
specific path.
To create a Breakpoint Sequence:
1. Right click on an existing breakpoint or shift click to select a group of existing
breakpoints and right click on the group.
2. From the pop-up menu, go to “Complex Breakpoint” and select “Add a New
Sequence”.
3. Enter a name for your sequence in the dialog box and click OK.
4. The breakpoint(s) will appear under the new sequence.
5. To add additional existing breakpoints to the sequence, right click on the break-
point and select Complex Breakpoint>Add to Name, where Name is the name of
the sequence.
6. To add new breakpoints to the sequence, right click on the sequence and select
“New Breakpoint”.
To select the Sequence Order:
1. Expand on a sequence to see all items.
2. Right click on an item and select Complex Breakpoints>Move Up or Complex
Breakpoints>Move Down. Sequence execution of breakpoints is bottom-up; the
last breakpoint in the sequence occurs first.
To Remove a Sequence or Breakpoint:
1. Right click on the item and select “Disable” to temporarily remove the item.
2. Right click on the item and select “Delete” to permanently remove the item.

 2011-2012 Microchip Technology Inc. DS52027B-page 89

MPLAB® X IDE User’s Guide

4.18.5 Set a Breakpoint Tuple (Device Dependent)

For MPLAB X IDE, a tuple represents an ANDed list of breakpoints. ANDed break-
points can be useful when a variable is modified in more than one location and you
need to break only when that variable is modified in one particular location.
Only two breakpoints can be ANDed and these must consist of one program memory
breakpoint and one data memory breakpoint. Breakpoint 1 AND breakpoint 2 must
occur at the same time before a program halt.
To create a Breakpoint Tuple:
1. Click on the icon in the upper left of the Breakpoints window to open the New
Breakpoint dialog.
2. Create an address breakpoint. Click OK to add it to the Breakpoints window.
3. Repeat steps 1 and 2 to create a data breakpoint.
4. Right click on one breakpoint and select Complex Breakpoint>Add to New Tuple.
5. Enter a name for your tuple in the dialog box and click OK.
6. The breakpoint will appear under the new tuple.
7. Right click on the other breakpoint and select Complex Breakpoint>Move to
Name, where Name is the name of the tuple.
To Remove a Tuple or Breakpoint:
1. Right click on the item and select “Disable” to temporarily remove the item.
2. Right click on the item and select “Delete” to permanently remove the item.

4.18.6 Breakpoint Applications

To determine the timing between breakpoints:
• Use the stopwatch (see Section 5.12 “Use the Stopwatch”).
To determine breakpoint resources:
• Open the Dashboard window (see Section 5.15 “View the Dashboard Display”)
to see the number of available and used breakpoints and whether software break-
points are supported.

4.18.7 Breakpoint Usage Considerations

Starter kits, in-circuit debuggers (including PICkit 2 and 3) and the MPLAB REAL ICE
in-circuit emulator support a limited number of breakpoints. The number of breakpoints
available is dependent on the device selected. To see the number of breakpoints avail-
able and keep track of the number you have used, see the Dashboard window
(5.15 “View the Dashboard Display”).
The following MPLAB X IDE features use breakpoints to accomplish their functions:
• Step Over
• Step Out
• Run to Cursor
• Reset to Main
If you attempt to use one of these features when no breakpoints are available, a dialog
will be displayed telling you that all resources are used.

DS52027B-page 90  2011-2012 Microchip Technology Inc.

 Basic Tasks

4.19 STEP THROUGH CODE

Use one of the stepping functions on the Debug menu and Debug toolbar to move
through code either from the beginning of code or after a breakpoint halt. Examine
changes in variable values (see next section) or determine if the program flow is
correct.
There are several ways to step through code:
• Step Over – Executes one source line of a program. If the line is a function call,
executes the entire function then stops.
• Step Into – Executes one source line of a program. If the line is a function call,
executes the program up to the function’s first statement and stops.
• Step Out – Executes one source line of a program. If the line is a function call,
executes the functions and returns control to the caller.
• Run to Cursor – Runs the current project to the cursor’s location in the file and
stop program execution.
In addition to the Editor window, you can single-step through code in the Disassembly
window (Section 5.13 “View the Disassembly Window”) and program memory in a
Memory window.
For more on stepping, see the table of contents for the NetBeans help topics under
C/C++/Fortran Development>Debugging C/C++/Fortran Applications with
gdb>C/C++/Fortran Debugging Sessions>Stepping Through Your C/C++/Fortran
Program.

 2011-2012 Microchip Technology Inc. DS52027B-page 91

MPLAB® X IDE User’s Guide

4.20 WATCH SYMBOL VALUES CHANGE

Watch the values of symbols that you select change in the Watches window. Determin-
ing if these values are as expected during program execution will help you to debug
your code.
In general, you must Pause from a Debug Run to be able to see updated values. How-
ever, some tools allow runtime updates. Check your tool documentation to see if it
supports this feature.

FIGURE 4-22: WATCHES WINDOW – PROGRAM PAUSE

To view the Watches window do one of the following:

• Select Window>Debugging>Watches to open the window.
• Click the Watches tab in the Output window if the window is already open.
To create a new watch directly:
You can add a symbol to the Watches window directly by doing one of the following:
• Double click in the name column and type in a global symbol, SFR, or absolute
address (0x300).
• Right click on a global symbol or SFR in the Editor window and select “New
Watch”.
• Select the global symbol or SFR in the Editor window and drag-and-drop it into the
Watches window.
To create a new watch using the New Watches dialog:
You can add a symbol or SFR to the Watches window by using the New Watch dialog:
• Right click in the Watches window and select “New Watch” or select Tools>New
Watch. Click the selection buttons to see either Global Symbols or SFRs. Click on
a name from the list and then click OK.
• Select the symbol or SFR name in the Editor window and then select “New
Watch” from the right click menu. The name will be populated in the window. Click
OK.
To create a new runtime watch:
Before you add a runtime watch to the Watches window, you need to set up the clock:
1. Right click on the project name and select “Properties”.
2. Click on the debug tool name (e.g., REAL ICE) and select the option category
“Clock”.
3. Set the runtime instruction speed.
To add a global symbol or SFR as a runtime watch, follow the instructions under “To
create a new watch using the New Watches dialog”, except select “New Runtime
Watch” instead of “New Watch”.
Symbols used in a runtime watch must be sized to match the device memory. That is,
you need 8-bit symbols when using an 8-bit device.

DS52027B-page 92  2011-2012 Microchip Technology Inc.

 Basic Tasks
To view symbol changes:
1. Debug Run and then Pause your program.
2. Click the Watches tab to make the window active.
3. For watch symbols, continue to Debug Run and Pause to see changing values.
For runtime watch symbols, continue Debug Run and watch the values change
as the program executes.
You must be in a debug session to see the values of symbols - global symbols, SFRs,
arrays, register bitfields, etc.
To change the radix of a watch symbol:
• Right click in the line of the symbol and select “Display Value As”.
To perform other tasks:
For more on watches, see Section 11.2.10 “Watches Window”.

 2011-2012 Microchip Technology Inc. DS52027B-page 93

MPLAB® X IDE User’s Guide

4.21 WATCH LOCAL VARIABLE VALUES CHANGE

Watch the values of local variables that you select change in the Variables window.
Determining if these values are as expected during program execution will help you to
debug your code.
In general, you must Pause from a Debug Run to be able to see updated values. How-
ever, some tools allow runtime updates. Check your tool documentation to see if it
supports this feature.

FIGURE 4-23: VARIABLES WINDOW – PROGRAM PAUSE

To view the Variables window do one of the following:

• Select Window>Debugging>Variables to open the window.
• Click the Variables tab in the Output window if the window is already open.
To view variable changes:
1. Debug Run and then Pause your program.
2. Click the Variables tab to view the window and see the local variable value.
To change the radix of a variable:
• Right click in the line of the variable and select “Display Value As”.
To perform other tasks:
For more on variables, see the table of contents for the NetBeans help topics under
C/C++/Fortran Development>Debugging C/C++/Fortran Applications with gdb>View-
ing C/C++/Fortran Program Information>C and C++ Variables and Expressions in the
IDE.

DS52027B-page 94  2011-2012 Microchip Technology Inc.

 Basic Tasks

4.22 VIEW/CHANGE DEVICE MEMORY (INCLUDING CONFIGURATION BITS)

MPLAB X IDE has flexible, abstracted memory windows that provide a more
customized view of the different types of device memory during debug. You must
Pause from a Debug Run to be able to see updated values in this window.

4.22.1 View Device Memory

1. Click a window in a pane to make the pane active. The memory window will open
in this pane.
2. Select a memory view from Window>PIC Memory Views. The available choices
are:
TABLE 4-5:MEMORY VIEWS – 8- AND 16-BIT DEVICES
Type Description
Program Memory All program memory (ROM) on the device
File Registers All file register (RAM) memory on the device
SFRs All Special Function Registers (SFRs)
Peripherals All SFRs by Peripheral
Configuration Bits All Configuration registers
EE Data Memory All EE Data memory on the device
Other Memory Other types of memory, such as User ID
TABLE 4-6:MEMORY VIEWS – 32-BIT DEVICES
Type Description
Execution Memory All Flash memory on the device
Data Memory All RAM memory on the device
Peripherals All Special Function Registers (SFRs)
Configuration Bits All Configuration registers
CPU Memory All CPU memory
Other Memory Other types of memory, such as User ID

3. Once a Memory window is open, you may further modify your view by selecting
the type of memory and memory format in drop-down boxes.
TABLE 4-7:MEMORY WINDOW OPTIONS – 8- AND 16-BIT DEVICES
Option Value Description
Memory File Registers All file register memory on the device
Program All program memory on the device
SFR All Special Function Registers (SFRs)
Configuration Bits All Configuration registers
EEPROM All EEPROM memory
User ID User ID memory
Format Data Data Memory (RAM)
Code Program Memory (ROM)
TABLE 4-8:MEMORY WINDOW OPTIONS – 32-BIT DEVICES
Option Value Description
Memory RAM Memory All RAM memory on the device
Flash Memory All Flash memory on the device
Peripheral All Special Function Registers (SFRs)
Configuration Bits All Configuration registers
CPU Memory All CPU memory
Memory All memory
User ID User ID memory
Format Data Data Memory (RAM)
Code Program Memory (ROM)

 2011-2012 Microchip Technology Inc. DS52027B-page 95

MPLAB® X IDE User’s Guide
4. After a Debug Run and then Pause, the window will populate with the memory
chosen.
5. You may close the window by clicking the “x” on the memory tab.

FIGURE 4-24: MEMORY WINDOW CONTENT

4.22.2 Change Device Memory

1. Change a value in the Memory window by clicking in the appropriate column and
selecting or entering new data. For some windows, the text will be red to show a
change.
2. The Fill memory feature is found on the context (right click) menu of most
Memory windows.
3. Use Debug>Discrete Debugger Operation to program the target and launch the
debugger with the changed data.
Note: The data will change only during the Debug Run. Your application code
is not changed.

4.22.3 Set Memory Window Options

Right clicking in the Memory window will pop up a context menu with various options
such as display options, fill memory, table import/export and output to file. For more
information on this menu, see Section 11.2.4.1 “Memory Window Menu”.

4.22.4 Set Configuration Bits

You must set Configuration bits in code. To aid you in developing your Configuration bit
settings, you can use the Configuration Bits window (see Section 4.22.1 “View
Device Memory”.)
You can temporarily change Configuration bits during a debug session in the Configu-
ration Bits window (see Section 4.22.2 “Change Device Memory”.) Once you have
the settings you want, select “Generate Source Code to Output”. You can then copy the
code from the Output window into your code.
You cannot edit the Configuration bits if you are not in a debug session. Also, if you
rebuild, all changes in the Configuration Bits window will be lost.
For a summary of Configuration bits settings for different devices, see Chapter
14. “Configuration Settings Summary”.

DS52027B-page 96  2011-2012 Microchip Technology Inc.

 Basic Tasks
FIGURE 4-25: CONFIGURATION BITS WINDOW

4.22.5 Refresh Selected Memory Windows

For Memory windows showing program, EEPROM, user ID, or configuration bits
memory, you can refresh the view by doing the following:
1. If you are debugging, halt your program unless your tool and device support
Debug Reads (see below).
2. Click on the icon named “Read Device Memory”.

Read Device Memory Icon

Debug Reads
For most devices, you must halt your program (Finish Debugger Session) before you
can read device memory. For some devices, you can read while in debug mode (Debug
Read). You will know that this is available as the “Read Device Memory” icon will not
be grayed-out when you are debugging.
Currently, MPLAB REAL ICE in-circuit emulator and MPLAB ICD 3 support Debug
Reads.
Debug Reads are done at target oscillator speeds so if the target is running very slow,
a read may take a long time. You can force a fast ICSP read by finishing the debug ses-
sion and then doing a read since ICSP reads will always be done when not in a debug
session.

 2011-2012 Microchip Technology Inc. DS52027B-page 97

MPLAB® X IDE User’s Guide

4.23 VIEW THE CALL STACK

For 16- and 32-bit devices, a software Call Stack window is available to view CALLs
and GOTOs in executing C code. This window is not applicable for assembly code. (It is
recommended that code optimization be turned off when using the call stack.)
The Call Stack window displays functions and their arguments listed in the order in
which they were called in the executing program.
To view the call stack:
1. Debug Run and then Pause your program.
2. Select Window>Debugging>Call Stack. A Call Stack window will open.
For more on the call stack, see the table of contents for the NetBeans help topic
C/C++/Fortran Development>Debugging C/C++/Fortran Applications with gdb>Using
the C/C++/Fortran Call Stack.

4.24 PROGRAM A DEVICE

Once your code is debugged, you can program it onto a target device. To do this click
Make and Program Device Project.
Other programming-related functions are shown in the table below. The first function is
activated by clicking on the button. For other functions, click on the down arrow next to
the button icon.

TABLE 4-9: PROGRAMMING FUNCTIONS ON TOOLBAR BUTTONS

Button
Function Details
Icon
Make and Program Device The project is built (if necessary) and the device is programmed.
The program will immediately begin execution on completion of pro-
gramming.
Program Device for Debugging The device is programmed from a debug image. The program will
immediately begin execution on completion of programming.
Program Device for Production The device is programmed from a production image. The program
will immediately begin execution on completion of programming.
Programmer to Go PICkit 3 Use the Programmer to Go feature of PICkit 3.
Read Device Memory Transfer what is in target memory to MPLAB X IDE.
Read Device Memory to File Transfer what is in target memory to the specified file.

Hold In Reset Toggle the device between Reset and Run.

Note: Not all programming functions are in the MPLAB X IDE. For additional programming support,
see the MPLAB IPE included with the MPLAB X IDE installation.

DS52027B-page 98  2011-2012 Microchip Technology Inc.

 MPLAB® X IDE
USER’S GUIDE
Chapter 5. Additional Tasks
5.1 INTRODUCTION
This chapter provides a guide for performing additional tasks in MPLAB X IDE, as
summarized in Performing Additional Tasks.

5.2 PERFORMING ADDITIONAL TASKS

The following steps shows how to perform more tasks in MPLAB X IDE

1. Open an MPLAB IDE v8 project in MPLAB X IDE by using the Import

MPLAB Legacy Project wizard.
Work with Projects 2. Open a prebuilt image (Hex, COF or ELF) using the Prebuilt Projects import
wizard.
3. Use Loadable Projects and Files to combine or replace project hex files.
This is useful for creating a combined bootloader and application hex file.
4. Create Library Projects to build their output as a library.
5. Create Projects from Other Embedded Projects or Sample Projects.
6. Work with Other Types of Files, not just Microchip ones. Also Modify or Cre-
ate Code Templates to change the default file templates that you use in
your project.
7. Switch Hardware or Language Tools used in your project.

1. Use the Stopwatch to determine the timing between breakpoints.

2. View the Disassembly Window to see disassembled code.
Debug Code 3. Use View The Call Graph to navigate function calls.
4. View the Dashboard Display to see project information such as breakpoint
resources, checksums and memory usage.

1. Improve Your Code* by using refactoring and profiling tools.

2. Control Source Code by using built-in file history or a version control
Manage Code system.
3. Collaborate on Code Development and Error Tracking* by using a team
server and an issue tracking system.

1. Add Plug-In Tools to aid code development.

Add Functionality
* To see this feature, refer to the Start Page, My MPLAB X IDE tab, “Extend MPLAB”
section, “Selecting Simple or Full-Featured Menus” topic.

 2011-2012 Microchip Technology Inc. DS52027B-page 99

MPLAB® X IDE User’s Guide

5.3 IMPORT MPLAB LEGACY PROJECT

The Import Legacy Project wizard will import an MPLAB IDE v8 project into an MPLAB
X IDE project with the following considerations:
• Settings that were saved in a workspace in MPLAB IDE v8 (such as tool settings)
will not be transferred to the new MPLAB X IDE project. Refer to the MPLAB IDE
v8 help for what is stored in a workspace (MPLAB IDE Reference>Operational
Reference>Saved Information.)
• For an MPLAB IDE v8 project using the MPLAB C Compiler for PIC24 MCUs and
dsPIC DSCs and a COFF debug file format:
• The MPLAB X IDE project will be converted to the ELF/DWARF debug file format
unless the project uses COFF libraries, in which case the project format will con-
tinue to be COFF.
• MPLAB IDE v8 is case insensitive to file extensions such as .c and .C. However,
MPLAB X IDE is case sensitive and associates .c to C code files and .C to C++
code files. Therefore, if you import an MPLAB IDE v8 project with C code speci-
fied as .C, MPLAB X IDE will incorrectly associated it as C++ code. Please
change the case of your file extensions before import to avoid this issue.

5.3.1 Open the Wizard

There are two ways to open this wizard - the Start Page option and the New Project
option.

5.3.1.1 START PAGE OPTION

• On the Start Page, click on the Learn & Discover tab, “Dive In” section, “Import
MPLAB Legacy Project” link. Or Select File>Import>MPLAB IDE v8 Project.
• The “Import Legacy Project” wizard opens.

5.3.1.2 NEW PROJECT OPTION

To open the New Project wizard, do one of the following:
• On the Start Page, click on the Learn & Discover tab, “Dive In” section, “Create
New Project” link.
• File>New Project (or Ctrl+Shift+N)
A wizard with launch to guide you through new project set up.
• Step 1. Choose Project: Select the “Microchip Embedded” category and choose
from the project type “Existing MPLAB IDE v8 Project”.
• The “Import Legacy Project” wizard opens.

5.3.2 Import Legacy Project Wizard

Follow the steps below to import your MPLAB IDE v8 project. Click Next> to move to
the next step.
• Step 1 or 2. Import Legacy Project: Enter or browse to the legacy project.
• Step 2 or 3. Select Device: Select the device you will be using in your application
from the “Device” drop-down list. To narrow your selection list, chose a Family
first.
• Step 3 or 4. Select Header: This step will appear if a header is available for your
selected device. To determine if a header is required for debug or if your device
has on-board debug circuitry, consult the Header Specification (DS51292 or
online help). Then choose whether or not to use a header.

DS52027B-page 100  2011-2012 Microchip Technology Inc.

 Additional Tasks
• Step 4 or 5. Select Tool: Select the development tool you will be using to develop
your application from the list.
The level of tool support for the selected device will be displayed next to the tool
name. That is, green for full support, yellow for beta support and red for no
support yet.
• Step 5 or 6. Select Compiler: Select the language tool (compiler) you will be
using to develop your application from the list.
The level of tool support for the selected device will be displayed next to the tool
name. That is, green for full support, yellow for beta support and red for no
support.
• Step 6 or 7. Select Project Name and Folder: It is recommended that you do not
change the default name and location to preserve maintainability of both projects.
File Locations:
The new project will not copy the source files into its folder, but instead will refer-
ence the location of the files in the v8 folder. To create an independent MPLAB X
IDE project, create a new project and copy the MPLAB IDE v8 source files to it.
Main Project:
Check the checkbox to make this project the main project on import.
File Formatting:
“ISO-8859-1” is the default character encoding used when importing a project
from MPLAB IDE v8. You should select the encoding that matches the one that is
used in the imported project. For example, if the MPLAB IDE v8 format is “950
(ANSI/OEM – Traditional Chinese Big5)”, then select “Big5” from the drop-down
list.

FIGURE 5-1: IMPORT LEGACY – SELECT PROJECT NAME AND FOLDER

• Step 7 or 8. Summary: Review the summary before clicking Finish. If anything is

incorrect, use the Back button to go back and change it.
The legacy project will open in the Project window.

 2011-2012 Microchip Technology Inc. DS52027B-page 101

MPLAB® X IDE User’s Guide

5.4 PREBUILT PROJECTS

Create a project from a prebuilt loadable image (Hex, COF, or ELF files) by using the
Import Image File wizard.

Note: To program a prebuilt image into a device, you will click the “Make and Pro-
gram Device” button even though it will only program the device (no make).

There are two ways to open this wizard – the Start Page option and the New Project
option.

5.4.1 Start Page Option

• On the Start Page, click on the Learn & Discover tab, “Dive In” section, “Import
Hex (Prebuilt) Project” link. Or Select File>Import>Hex/ELF (Prebuild) File.
• The “Import Image File” wizard opens.

5.4.2 New Project Option

To open the New Project wizard, do one of the following:
• On the Start Page, click on the Learn & Discover tab, “Dive In” section, “Create
New Project” link.
• File>New Project (or Ctrl+Shift+N)
A wizard with launch to guide you through new project set up.
• Step 1. Choose Project: Select the “Microchip Embedded” category and choose
from the project type “Prebuilt (Hex, Loadable Image) Project”.
• The “Import Image File” wizard opens.

5.4.3 Import Image File Wizard

Follow the steps below to import your image file. Click Next> to move to the next step.
• Step 1 or 2. Import Image File: Select the name and location of your image file.
You may browse to a location.
• Step 2 or 3. Select Device: Select the device you will be using in your application
from the “Device” drop-down list. To narrow your selection list, chose a Family
first.
• Step 3 or 4. Select Header: This step will appear if a header is available for your
selected device. To determine if a header is required for debug or if your device
has on-board debug circuitry, consult the Header Specification (DS51292 or
online help). Then choose whether or not to use a header.
• Step 4 or 5. Select Tool: Select the development tool you will be using to develop
your application from the list.
The level of tool support for the selected device will be displayed next to the tool
name. That is, green for full support, yellow for beta support and red for no
support yet.
• Step 6 or 7. Select Project Name and Folder: Select a name and location for
your new project. You may browse to a location.
• Step 7 or 8. Summary: Review the summary before clicking Finish. If anything is
incorrect, use the Back button to go back and change it.
The new project will open in the Project window.
For information on exporting a project as hex, see Section 11.2.7.2 “Projects Win-
dow – Project Menu”.

DS52027B-page 102  2011-2012 Microchip Technology Inc.

 Additional Tasks

5.5 LOADABLE PROJECTS AND FILES

Use loadable projects and files to combine projects, combine a project with hex files or
replace the project hex file. Loadable projects or files are useful for creating combined
bootloader and application code.
The options are listed below.
TABLE 5-1: LOADABLE OPTIONS
Add Loadable Project(s) Load one or more existing projects into your current project. When
you build your current project, all projects will be built and the hex
files will be combined into one. All debug files will be combined as
well (COFF or ELF).
Add Loadable File(s) Load one or more existing hex files into your current project. When
you build your current project, the hex file will be combined with the
other hex files into one file.
Note: You will no longer be able to debug the project that contains
hex file(s). Use Loadable Projects for debugging.
Add Alternate File Load an alternate hex file to be used.
To set up and use loadables, see:
• Project Window - Loadables Set Up
• Project Properties Window - Loading Set Up
• Using Loadables to Combine a Bootloader and Application
• The Preferred Method to Use Loadables

5.5.1 Project Window - Loadables Set Up

Right Click on the “Loadables” folder in the Project window (Figure 5-2) and select an
option:
• Add Loadable Project - Select to add an existing project to your current project.
Repeat to add additional projects.
• Add Loadable Files - Select to add an existing hex file to your current project.
Repeat to add additional hex files.
• Properties - Open the Project Properties window for Loading. See
Section 5.5.2 “Project Properties Window - Loading Set Up”.
Build your current project to build all projects and combine hex files into one. Any debug
files will also be combined.

FIGURE 5-2: PROJECT WINDOW - LOADABLES FOLDER

 2011-2012 Microchip Technology Inc. DS52027B-page 103

MPLAB® X IDE User’s Guide

5.5.2 Project Properties Window - Loading Set Up

Open the Project Properties window (File>Project Properties) and click on “Loading”
(Figure 5-3).

FIGURE 5-3: PROJECT PROPERTIES - LOADING

To combine the current project with other projects

1. Click Add Loadable Project. Browse to a project, select it and click Add.
2. Select a build configuration to use for this project in the drop-down box under
“Configuration”. If you have not added different configurations to this project, you
will only see “default”.
3. Ensure the “Build” checkbox is checked if you want to build this project when you
build the current project.
4. If you have added more than one project, the order shown here will determine
the order in which the hex files will be added to the current project’s hex file. Use
Up and Down to change the order.
5. Click Apply or OK to accept the changes.
The next time you build the current project, the projects listed here will also be built (if
“Build” is checked) and their hex files will be combined with the current project’s hex file
to create a single output hex file. Any debug files will also be combined.
To combine the current project hex file with other hex files
1. Click Add Loadable File. Browse to a hex file, select it and click Add.
2. If you have added more than one file, the order shown here will determine the
order in which the hex files will be added to the current project’s hex file. Use Up
and Down to change the order.
3. Click Apply or OK to accept the changes.
The next time you build the current project, the hex files listed here will be combined
with the current project’s hex file to create a single output hex file.

DS52027B-page 104  2011-2012 Microchip Technology Inc.

 Additional Tasks
To load an alternative hex file:
1. Click to check “Load this hex file on run or program builds only (debug not
affected)”.
2. Browse to the desired hex file and select it. Select how you want the file refer-
enced (Auto, Relative, Absolute) and then click Add.
The next time you build the current project, the alternative hex file will load on build
complete.

5.5.3 Using Loadables to Combine a Bootloader and Application

To combine a bootloader with application code:
1. Create one project for your application and one project for your bootloader.
2. Load the bootloader project or hex file into the application project. See
Section 5.5.1 “Project Window - Loadables Set Up” or
Section 5.5.2 “Project Properties Window - Loading Set Up” for how to do
this.
The next time you build your application project, the resulting hex file will be a combined
bootloader/application hex file. Any debug files will also be combined.

5.5.4 The Preferred Method to Use Loadables

The recommended way to use loadables is:
1. Select the project that sets the device configuration bits and initialization as the
main project (right click and select “Set as Main Project”).
2. Add the other projects as loadables to this main project. If the project being
loaded has more than one configuration, be sure to specify it when loading.
Specifying the project containing the loadables as the main project ensures that a
change in any loadable will be picked up by the build when the build button is pressed.

 2011-2012 Microchip Technology Inc. DS52027B-page 105

MPLAB® X IDE User’s Guide

5.6 LIBRARY PROJECTS

Create a new library project that uses an IDE-generated makefile to build your project
as a library file instead of an executable.

FIGURE 5-4: LIBRARY PROJECT EXAMPLE

To begin, open the New Project wizard by doing one of the following:
• On the Start Page, click on the Learn & Discover tab, “Dive In” section, “Create
New Project” link.
• File>New Project (or Ctrl+Shift+N)
A wizard will launch to guide you through new project set up. Click Next> to move to
the next step.
• Step 1. Choose Project: Select the “Microchip Embedded” category and choose
from the project type “Library Project”.
• Step 2. Select Device: Select the device you will be using in your application
from the “Device” drop-down list. To narrow your selection list, chose a Family
first.
• Step 3. Select Header: This step will appear if a header is available for your
selected device. To determine if a header is required for debug or if your device
has on-board debug circuitry, consult the Header Specification (DS51292 or
online help). Then choose whether or not to use a header.
• Step 4. Select Tool: Select the development tool you will be using to develop
your application from the list.
The level of tool support for the selected device will be displayed next to the tool
name. That is, green for full support, yellow for beta support and red for no
support yet.
• Step 5. Select Compiler: Select the language tool (compiler) you will be using to
develop your application from the list.
The level of tool support for the selected device will be displayed next to the tool
name. That is, green for full support, yellow for beta support and red for no
support.
• Step 6. Select Project Name and Folder: Select a name and location for your
new project. You may browse to a location.
The new project will open in the Project window.

DS52027B-page 106  2011-2012 Microchip Technology Inc.

 Additional Tasks

5.7 OTHER EMBEDDED PROJECTS

MPLAB X IDE can create a project from selected, other embedded projects.
1. Select File>New Project.
2. Click on “Other Embedded” under “Categories” and select from a list of available
embedded projects.
3. Continue to create an MPLAB X IDE project.
This feature imports your existing files into an MPLAB X IDE project. Conversion of
other embedded project settings or code is not yet available.
For information on how to work with MPLAB X IDE, see:
• Chapter 3. “Tutorial”
• Chapter 4. “Basic Tasks”
For information on available compilers, see:
• http://www.microchip.com/xc

5.8 SAMPLE PROJECTS

Create a sample project to help you learn about Microchip devices, tools and MPLAB
X IDE.
1. Select File>New Project.
2. Click on “Samples>Microchip Embedded” under “Categories” and select from a
list of available embedded projects (that blink demo board lights) or template
projects. Read the Description for more information.
Part numbers for demo boards are as follows:
Explorer 16 Demo Board: DM240001
PICDEM 2 Plus: DM163022-1

5.9 WORK WITH OTHER TYPES OF FILES

When selecting File>New, you are presented with many types of files. Using Microchip
compiler files has been explored previously. However, there are other types of files you
can select depending on your project language tool or need to create a specific file.

TABLE 5-2: FILE TYPES

Category File Type
Microchip Embedded Files for language tools that are supported in MPLAB X IDE.
Select your compiler folder to see the available file types.
C Generic C files.
C++ Generic C++ files.
Assembler Generic assembly files.
Shell Scripts Shell script files: Bash, C, Korn, etc.
Makefiles Makefile files.
XML XML files.
Other Other types of files, such as HTML, JavaScript, etc.
If you do not see the type of file you want listed here, select “Empty
File”. In the next window, name the file with the desired extension.

 2011-2012 Microchip Technology Inc. DS52027B-page 107

MPLAB® X IDE User’s Guide

5.10 MODIFY OR CREATE CODE TEMPLATES

When you create a file to add to your project (Section 4.9 “Create a New File”), a tem-
plate is used for the new file. To change this template, select Tools>Templates and then
“Open in Editor” to edit a template. You may also use “Add” or “Duplicate” in this dialog
to create new templates.
“New Folder” can be used to create a new folder to hold templates. Be aware that
MPLAB X IDE filters out all but Microchip Embedded, Shell Scripts, Makefiles and
Other, so files or folders should be created under those folders.

FIGURE 5-5: TEMPLATE MANAGER

You may set template options by selection Tools>Options (mplab_ide>Preferences for

Mac OSX), Editor button, Code Templates tab (Figure 5-6).
An option of note for C code is the “fcom” option. In an Editor window, type “fcom” and
then press “Tab” to insert the following text into the source code:
// <editor-fold defaultstate="collapsed" desc="comment">
// </editor-fold>

This option allows you to hide/view sections of code.

FIGURE 5-6: TEMPLATE OPTIONS

DS52027B-page 108  2011-2012 Microchip Technology Inc.

 Additional Tasks

5.11 SWITCH HARDWARE OR LANGUAGE TOOLS

When you open an existing project and you have connected a hardware tool that is dif-
ferent from the one you specified in your project, MPLAB X IDE will pop up a dialog
asking if you would like to make the new hardware tool the project tool.

FIGURE 5-7: SWITCH HARDWARE TOOL DIALOG

X HW Tool not Found

HW Tool SN#xxxx was selected in the project configuration, but does not appear to
be connected. HW Tool SN#yyyy is currently connected. Would you like to use this
HW Tool instead?

OK Cancel

You may also plug in two or more hardware tools and switch between them in the
Project Properties dialog (File>Project Properties).
To switch between different versions of compiler toolchains (language tools), again use
the Project Properties dialog.

 2011-2012 Microchip Technology Inc. DS52027B-page 109

MPLAB® X IDE User’s Guide

5.12 USE THE STOPWATCH

Use the stopwatch to determine the timing between two breakpoints.
To use the Stopwatch:
1. Add a breakpoint where you want to start the stopwatch.
2. Add another breakpoint where you want to stop the stopwatch.
3. Select Window>Debugging>Stopwatch. Click on the Properties icon on the left
of the window and select the start and stop breakpoints.
4. Debug Run the program again to get the stopwatch timing result.

FIGURE 5-8: STOPWATCH WINDOW WITH CONTENT

The stopwatch has the following icons on the left side of the window:
Icon Description
Properties Set stopwatch properties. Select one current breakpoint or
trigger to start the stopwatch and one to stop the stopwatch.
Reset Stopwatch on Run Reset the stopwatch time to zero on the start of a run.
Clear History Clear the stopwatch window.
Clear Stopwatch (Simulator Only) Reset the stopwatch after you reset the
device.

5.13 VIEW THE DISASSEMBLY WINDOW

View disassembled code in this window. Select Window>Output>Disassembly Listing
File to open the window.
This information may also be found in the listing file produced by the linker. Open this
file by selecting File>Open File and browsing for the ProjectName.lst file.
A quick way to view the entire disassembly file is to right click in the disassembly win-
dow and select “Disassembly Listing File”.

5.14 VIEW THE CALL GRAPH

The Call Graph window displays a tree view of either the functions called from a
selected function, or the functions that call that function.
To view the call graph:
1. Select Window>Output>Call Graph.
2. Select the function in the Code window.
3. Right click on the highlighted function and select “Show Call Graph” from the
drop-down menu.
For more information, see the table of contents for the NetBeans help topic
C/C++/Fortran Development>C/C++/Fortran Project Basics>Navigating and Editing
C/C++/Fortran Source Files>Using the Call Graph.

DS52027B-page 110  2011-2012 Microchip Technology Inc.

 Additional Tasks

5.15 VIEW THE DASHBOARD DISPLAY

Select Window>Dashboard to display project information.

FIGURE 5-9: DASHBOARD DISPLAY

The project displayed will either be:

• The active project in the Project window if no main project is selected (Run>Set
Main Project>None.) Click on a project in the Project window to make it active.
• The main project. No other project, active or inactive, will be displayed.
Features of the Dashboard window are listed in the tables below.
TABLE 5-3: DASHBOARD GROUPS

Group Definition and Content

Device The project device.
Any status flags generated during a Run or Debug Run.
The checksum for the built program, i.e., you must build to see this.
Compiler The compiler toolchain (compiler, assembler, linker, etc.) used in the project.
Toolchain Includes the path to the executable files.
Memory The type and amount of memory used by the project, as well as memory
reserved for debugging.
Resources The number of hardware breakpoints available for the project device.
(Breakpoints) How many breakpoints are in use at the current time.
Are software breakpoints supported on the project device.
Debug Tool Connection status of the debug tool.

For hardware debug tools, the connection is only active during a Debug
Run, Run, or programming. Otherwise it is inactive. To keep the tool con-
nection active at all times, go to Tools>Options (mplab_ide>Preferences for
Mac OSX), Embedded button, Generic Settings tab, and check “Maintain
active connection to hardware tool”.

Click the “Refresh Debug Tool Status” button to see hardware debug tool
firmware versions and current voltage levels.

 2011-2012 Microchip Technology Inc. DS52027B-page 111

MPLAB® X IDE User’s Guide
TABLE 5-4: SIDEBAR ICONS
Icon Function

Display the Project Properties dialog.

Refresh debug tool status. Click this to see hardware debug tool details.

Toggle software breakpoint. Click to alternately enable or disable software break-

points.

Get device data sheet from Microchip web site. Click to either open a saved, local
data sheet or open a browser to go to the Microchip web site to search for a data
sheet.

5.16 IMPROVE YOUR CODE

Improve your code by using code refactoring and/or profiling.

Note: To see this feature, refer to the Start Page, My MPLAB X IDE tab, “Extend
MPLAB” section, “Selecting Simple or Full-Featured Menus” topic.

Refactoring code is a method of making code simpler without changing its

functionality. Currently you can do the following with C code:
• Find function usages throughout files
• Rename functions and parameters throughout files
For more information, see Section 7.6 “C Code Refactoring”.
Profiling code is the examination of CPU Usage, Memory Usage, and Thread Usage
tools, all while the program is running. The profiling tools run automatically whenever
you run your C project.

DS52027B-page 112  2011-2012 Microchip Technology Inc.

 Additional Tasks

5.17 CONTROL SOURCE CODE

MPLAB X IDE has a built-in local file history feature, compliments of the NetBeans plat-
form. This feature provides built-in versioning support for local projects and files, similar
to conventional version control systems. Available tools include a local DIFF and file
restoration. Right click on a file in the Project or File window to see Local History
options.
To see local history for a file:
• Right click on the file in the Project or File window and select Local History>Show
Local History. Any past changes to the file should be listed here.
• Right click on the file in the Project or File window and select Local History>Revert
to. The Revert to dialog opens with any previous versions of the document. Select
one and click OK to revert to that version.
If you prefer to use a full version control system, support is available for CVS,
Subversion, and Mercurial.
Source control is available under:
• Tools>Options (mplab_ide>Preferences for Mac OSX), Miscellaneous, Version-
ing – Set up version control programs (see Figure 5-10).
• Team menu – Select version control program submenus.
• Window>Versioning – Open version control windows.

FIGURE 5-10: VERSION CONTROL OPTIONS

 2011-2012 Microchip Technology Inc. DS52027B-page 113

MPLAB® X IDE User’s Guide
Project files that need to be saved into a repository:
An MPLAB X IDE project is defined as a directory containing an nbproject subdirec-
tory. This nbproject contains the files needed to build the projects images. Some of
the files under nbproject are regenerated as needed. So, there is no need to commit
them to a version control repository. The files that are regenerated and therefore not
needed to be saved in a repository are:
• nbproject/Makefile-*
• nbproject/Package-*
• nbproject/private
• nbproject/private/*
where private is a directory.
In the MPLAB X IDE project directory there is another Makefile file that is only cre-
ated when the project is created; therefore it should be committed to the repository.
For more information:
For more on using local file history and/or source control, see the table of contents for
the NetBeans help topics under IDE Basics>Version Control and File History.
For further information on the source control programs above, see:
• CVS – http://www.nongnu.org/cvs/
• Subversion – http://subversion.tigris.org/
• Mercurial – http://mercurial.selenic.com/

DS52027B-page 114  2011-2012 Microchip Technology Inc.

 Additional Tasks

5.18 COLLABORATE ON CODE DEVELOPMENT AND ERROR TRACKING

Collaborate on code development with your group using a team server (such as
Kenai.com) supported inside MPLAB X IDE.

Note: To see this feature, refer to the Start Page, My MPLAB X IDE tab, “Extend
MPLAB” section, “Selecting Simple or Full-Featured Menus” topic.

Supporting menu items are:

• Team>Team Server – The main team server menu. Log into your account, create
or open your project, share your project, get resources, send a chat message or
show your contact list.
• File>Open Team Project – Open an existing team project.
• Windows>Team – View your project in the Team window.
• Windows>Chat – Open the Chat window for team interaction.
Collaborate on tracking bugs by using issue tracking systems, namely Bugzilla™ and
JIRA® (plug-in required). Supporting menu items are:
• Windows>Services – Right click on “Issue Tracker” to add an issue tracker.
• Team>Find Issues – In the Issue Tracker window, select the project’s issue
tracker, select criteria, and click Search.
• Team>Report Issues – In the Issue Tracker window, select the project’s issue
tracker, specify the issue details, and click Submit.
For more on team projects and issue tracking, see the table of contents for the Net-
Beans help topic IDE Basics>Collaborative Development.
To find out more about these tools, see the following:
• Kenai – http://kenai.com/
• Bugzilla – http://www.bugzilla.org/
• JIRA – http://www.atlassian.com/software/jira/

 2011-2012 Microchip Technology Inc. DS52027B-page 115

MPLAB® X IDE User’s Guide

5.19 ADD PLUG-IN TOOLS

MPLAB IDE v8 plug-in tools like DMCI and MATLAB will be available for MPLAB X IDE
from the Plugin Manager (Tools>Plugins). The Macro controls which appear under the
MPLAB IDE v8 Tools menu are really an editor feature and so exist under the Edit menu
for MPLAB X IDE.
• Configure Microchip Update Center
• Add Plug-Ins
• Upgrade Plug-Ins

5.19.1 Configure Microchip Update Center

To add a Microchip plug-in, you must first configure the Microchip Update Center in the
Plugin Manager:
1. Select Tools>Plugins and click the Settings tab.
2. Click the Add button to open the Update Center Customizer dialog.
3. Enter “Microchip Update Center” for the name.
4. Enter the following as the URL:
http://ww1.microchip.com/downloads/mplab/X/plugins/updates.xml
5. Click OK.

FIGURE 5-11: CONFIGURE MICROCHIP UPDATE CENTER

DS52027B-page 116  2011-2012 Microchip Technology Inc.

 Additional Tasks

5.19.2 Add Plug-Ins

To view and add plug-ins to MPLAB X IDE:
1. Click on the Available Plugins tab.
2. Select your plug-in by checking its checkbox.
3. Click Install.
4. Follow the on-screen instructions to download and install your plug-in.
Note: Some plugins may be dependent on modules in other plugins in order for
the functionality to be implemented. The Plugins Manager warns you when
this is the case.
5. Look for your tool under Tools>Embedded. If you do not see it, you may need to
close and re-open MPLAB X IDE.
Click the Help button to read more about installing plug-ins.

FIGURE 5-12: AVAILABLE MICROCHIP PLUG-IN TOOLS

5.19.3 Upgrade Plug-Ins

Installing a new version of MPLAB X IDE will NOT update your installed plug-ins.
Plug-ins are tested against a versioned interface of a release. Not all plug-ins can be
migrated between versions so they are not carried over. This is true also for NetBeans.
To upgrade your plug-in to a newer version or add it for a newer version of MPLAB X
IDE, please us the Plugin dialog in Section 5.19.2 “Add Plug-Ins”.

 2011-2012 Microchip Technology Inc. DS52027B-page 117

MPLAB® X IDE User’s Guide
NOTES:

DS52027B-page 118  2011-2012 Microchip Technology Inc.

 MPLAB® X IDE
USER’S GUIDE
Chapter 6. Advanced Tasks
6.1 INTRODUCTION
This chapter provides a guide for performing advanced tasks in MPLAB X IDE. Other
feature are discussed in Chapter 4. “Basic Tasks” and Chapter 5. “Additional
Tasks”.
• Multiple Projects
• Multiple Configurations
• Log Data
• Customize Toolbars

6.2 MULTIPLE PROJECTS

MPLAB X IDE allows you to work with more than one project.
If you need to work on more than one project at a time, multiple projects may be opened
in MPLAB X IDE and viewed in the Projects window. For more on this window, see
Section 11.2.7 “Projects Window”.

FIGURE 6-1: MULTIPLE PROJECTS IN THE PROJECTS WINDOW

 2011-2012 Microchip Technology Inc. DS52027B-page 119

MPLAB® X IDE User’s Guide
Active Projects
Projects may be made active by clicking on them in the Projects window.
Main Project
One project is selected as the main project by doing one of the following:
• right clicking the project name and selecting “Set as Main Project”.
• selecting Run>Set Main Project.
The main project name will then appear in bold.

To work with multiple projects:

1. Create (File>New Project) or open (File>Open Project) two or three projects.
2. Start debugging each project, i.e., click on a project in the Project window and
then select Debug>Debug Project.
3. Open the Sessions window (Window>Debugging>Sessions) and you can switch
between any currently running debug sessions.
When one debug session is switched to another, the Watch window and variables plus
the memory will switch to show the currently selected project being debugged. The Sta-
tus bits should also follow the debug project. The Dashboard will follow the last selected
whether it is a debug project or a project in the project window. This is by design.

DS52027B-page 120  2011-2012 Microchip Technology Inc.

 Advanced Tasks

6.3 MULTIPLE CONFIGURATIONS

MPLAB X IDE allows multiple configurations for the same project. This may be useful
for code that can be compiled on multiple platforms (such as the Microchip Application
Libraries Demo Projects.)
When you create a new project, a “default” configuration is created. To create your own
configuration, start by doing one of the following:
• Use the drop down menu on the toolbar and select “Customize” (Figure 6-2). The
Project Properties dialog will open.
• Open the Project Properties dialog by right clicking on the project name and
selecting “Properties”.

FIGURE 6-2: PROJECT CONFIGURATION DROP-DOWN BOX

In the Project Properties dialog, click Manage Configurations to open the

Configurations dialog (Figure 6-3). Existing configurations can be renamed or a new
configuration can be added or duplicated from an existing one.
When more than one configuration is created for a project, the active one can be
selected from Manage Configurations or from the drop-down menu.

FIGURE 6-3: PROJECT PROPERTIES – CONFIGURATIONS DIALOG

 2011-2012 Microchip Technology Inc. DS52027B-page 121

MPLAB® X IDE User’s Guide

6.3.1 Add a New Configuration

If a new configuration is added, the device and language tools must be assigned in the
Project Properties dialog.

FIGURE 6-4: NEW CONFIGURATION

6.3.2 Add a Duplicate Configuration

You can add a configuration that is the duplicate of an existing one and then make edits
from there. A good use of a duplicate configuration is for debugging.
To set up a debug configuration:
1. In the Configuration dialog, select a project configuration and click Duplicate.
2. Click Rename and enter “Debug” in the New Configuration Name dialog.
3. Click OK twice to return to the Project Properties dialog. The Debug configura-
tion (Conf: Debug) should now be visible.
4. Click on the compiler or assembler in the toolchain. Under the “General” options
category, click on the Preprocessor macro text box.
5. In the Preprocessor Macros dialog, enter __DEBUG and click OK.

DS52027B-page 122  2011-2012 Microchip Technology Inc.

 Advanced Tasks
You may now switch to the Debug configuration when you want to debug. You can use
the preprocessor macro in conditional text:
#ifdef __DEBUG
fprintf(stderr,"This is a debugging message\n");
#endif

FIGURE 6-5: DEBUG CONFIGURATION

 2011-2012 Microchip Technology Inc. DS52027B-page 123

MPLAB® X IDE User’s Guide

6.4 LOG DATA

Create a log file to capture your program execution and debug problems.
To set up a log file:
1. Select Tools>Options (mplab_ide>Preferences for Mac OSX), Embedded but-
ton, General Settings tab.
2. Select a logging level from the drop-down box. For details see
Section 11.2.8.3 “Generic Settings tab”.

Note: The higher the logging level, the more data is collected, but the slower your
application will run.

3. Select a location (path) for the log file.

To log a crash:
1. Set up the log file using logging level “Finest”.
2. Take note of the log file name and location.
3. Repeat the steps to cause a crash.
4. Find the log file(s) and send to technical support (see “Customer Support”.)
To log a problem:
1. Set up the log file using logging level “Finest”.
2. Open the log file the Output window by selecting View>IDE log.
3. Right click in the window and select “Clear”.
4. Repeat the steps to cause the problem.
5. Right click in the window and select “Save As” to save the text to a file.
6. Send the file to technical support (see “Customer Support”.)

DS52027B-page 124  2011-2012 Microchip Technology Inc.

 Advanced Tasks

6.5 CUSTOMIZE TOOLBARS

You can customize MPLAB X IDE toolbars using the Customize Toolbars window.
Select View>Toolbars>Customize to open the window.
Available icons include Clean Only, Run, Set PC to Cursor, etc.
Add a function to a toolbar:
• Drag an icon from the Customize Toolbars window to a toolbar on the desktop.
Remove a function from a toolbar:
• Drag an icon from a toolbar on the desktop to the Customize Toolbars window.
Add your own toolbar:
• Click “New Toolbar” and name the new toolbar.
Change toolbar icon size:
• Check the checkbox “Small Toolbar Icons” to make the icons smaller.
• Uncheck to make the icons larger.
Revert to default toolbar:
• Click “Reset Toolbars”.
Available functions are shown in the tables below.

TABLE 6-1: BUILD FUNCTIONS

Function Details
Make Performs a make (builds project files if they have been
updated) without cleaning.
Make Clean Cleans (remove previously built project files) and makes
the project.

TABLE 6-2: DEBUG FUNCTIONS

Function Details
New Data Breakpoint Sets a new data breakpoint at the specified line,
exception, or method.
New Run Time Watch Adds the specified symbol to watch that will change value
as the program runs/executes.
New Watch Enters an expression or select an SFR to watch in the
Watches window.
PIC AppIO Opens the PIC AppIO window. Your debug tool and
device must support Application I/O. See your debug tool
documentation for details.
Program Device for Debugging Programs the device from a debug image. The program
Main Project will immediately begin execution on completion of pro-
gramming.
Disassembly Opens the disassembly window.
Disconnect from Debug Tool Disconnects communications between MPLAB® X IDE
and the debug tool. To reconnect, select Run/Debug Run.
Focus Cursor at PC Moves the cursor to the current PC address.
PC Profiling Opens the PC Sampling window. See MPLAB REAL ICE
in-circuit emulator documentation for more on PC
sampling and profiling.
Reset Resets the device.
Set PC at Cursor Sets the program counter (PC) value to the line address
of the cursor.

 2011-2012 Microchip Technology Inc. DS52027B-page 125

MPLAB® X IDE User’s Guide
TABLE 6-2: DEBUG FUNCTIONS (CONTINUED)
Function Details
Step Instruction Executes one machine instruction. If the instruction is a
function call, executes the function and returns control to
the caller.
Status Toolbar Action Displays the status toolbar.
Launch Debugger Main Project Launches the debugger for the main project. This is the
final step of the discrete build process: Build, Program
Target, Launch Debugger.
This is useful for changing Memory window setting during
debug and using starter kits.
Debug Main Project Debugs the main project.
New Watch Enters an expression to watch in the Watches window.
Attach Debugger Connects communications between MPLAB® X IDE and
the debug tool.
A debug tool is automatically connected during a Run or
Debug Run, and disconnected at the end of a run. To
keep the debug tool connected at all times, check
Tools>Options (mplab_ide>Preferences for Mac OSX),
Embedded button, General Settings tab, “Maintain
active connection to hardware tool”.
Continue Resumes debugging after “Pause” until the next break-
point or the end of the program is reached.
Debug File Starts debugging session for currently selected file.
Debug Test File Starts debugging test for file in JUnit. (Java related)
Apply Code Changes Apply any changes in the code to the executing program.
Finish Debugger Session Ends the debugging session.
Make Callee Current Makes the method being called the current call. Only
available when a call is selected in the Call Stack window.
Make Caller Current Makes the calling method the current call. Only available
when a call is selected in the Call Stack window.
Pause Pauses debugging. Use “Continue” to resume.
Run to Cursor Runs the current project to the cursor’s location in the file
and stop program execution.
Step Into Executes one source line of a program. If the line is a
function call, executes the program up to the function’s
first statement and then stops.
Step Over Expression Steps over the expression and then stops the debugging.
Step Out Executes one source line of a program. If the line is a
function call, executes the function and returns control to
the caller.
Step Over Executes one source line of a program. If the line is a
function call, executes the entire function and then stops.

DS52027B-page 126  2011-2012 Microchip Technology Inc.

 Advanced Tasks
TABLE 6-3: EDIT FUNCTIONS
Function Details
Next Bookmark Cycles forward through the bookmarks.
Previous Bookmark Cycles backward through the bookmarks.
Clear Document Bookmarks Clears all bookmarks in the document.
Quick Search Displays the Quick Search toolbar.
Find in Projects Finds specified text, object names, object types within
projects.
Replace in Projects Replaces text, object names, object types within projects.
Copy Copies the current selection to the clipboard.
Cut Deletes the current selection and places it on the clip-
board.
Delete Deletes the current selection.
Find Finds a text string.
Paste Pastes the contents of the clipboard into the insertion
point.
Redo Reverses (one at a time) a series of Undo commands.
Undo Reverses (one at a time) a series of editor actions, except
Save.

TABLE 6-4: HELP FUNCTIONS

Function Details
Start Page Displays the Start Page.
Help Displays the Help window.

TABLE 6-5: PROFILE FUNCTIONS

Function Details
Start Sampling IDE Begins sampling for PC Profiling/Sampling. See MPLAB
REAL ICE in-circuit emulator documentation for more on
PC sampling and profiling.

 2011-2012 Microchip Technology Inc. DS52027B-page 127

MPLAB® X IDE User’s Guide
TABLE 6-6: PROJECT FUNCTIONS
Function Details
Programmer to Go PICkit 3 Main Uses the Programmer to Go feature of PICkit 3.
Project
Erase Device Memory Main Proj- Erases device memory for the main project.
ect
Hold in Reset Toggle the device between Reset and Run.
Make and Program Device Main The main project is built (if necessary) and the device is
Project programmed. The program will immediately begin execu-
tion on completion of programming.
Read Device Memory Main Project Transfer what is in target memory to MPLAB X IDE.
Read Device Memory to File Transfer what is in target memory to the specified file.
Build Main Project Builds all the files of the main project.
Build for Debugging Main Project Builds all the files of the main project for debugging.
Clean and Build Main Project Cleans (removes) all generated files and then rebuilds all
the files of the main project.
Build Project Builds all the files of the selected project.
Clean Main Project Cleans (removes) all generated files of the main project.
Clean Project Cleans (removes) all generated files of the selected proj-
ect.
Compile File Compiles the selected file using the project compiler.
New File Launches New File wizard.
New Project Launches New Project wizard.
Open Project Opens an existing project.
Clean and Build Project Cleans (removes) all generated files and then rebuilds all
the files of the selected project.
Run Main Project The main project is built (if necessary) and the device is
programmed. The program will immediately begin execu-
tion on completion of programming.
Same as “Make and Program Device Main Project”.
Run Project The selected project is built (if necessary) and the device
is programmed. The program will immediately begin exe-
cution on completion of programming.
Run File Runs the currently selected file.
Test Project Starts JUnit test for current project. (Java related)
Test File Starts JUnit test for current file. (Java related)
Open Required Projects Opens dependent projects.
Projects Opens the Projects window.
Files Opens the Files window.

DS52027B-page 128  2011-2012 Microchip Technology Inc.

 Advanced Tasks
TABLE 6-7: CVS* FUNCTIONS
Function Details
Commit Commits local changes to files into the repository.
Diff Shows file revisions between repository versions and
your local working copies.
Show Annotations Displays commit message, author, date, and revision
number information in the left margin of files open in the
Source Editor.
Revert Modifications Reverts local versions of files to versions stored in the
repository.
Update Updates local versions of files with changes committed to
the repository.
* CVS is not included with MPLAB X IDE and must be acquired separately. For more on CVS,
see http://www.nongnu.org/cvs.

TABLE 6-8: SYSTEM FUNCTIONS

Function Details
Next Error Scrolls the Source Editor to the line that contains the
next build error.
Previous Error Scrolls the Source Editor to the line that contains the
previous build error.
Run SQL* Runs SQL statements and scripts.
SQL* History Provides a list of SQL statements that have been previ-
ously executed in the SQL Editor.
Keep Prior Tabs Toggles keeping SQL* results tabs from the previous
execution open/closed.
Open File Opens the Open dialog.
Properties Opens the Project Properties window.
Save Saves the current file.
Save All Saves all open files. If the “Compile on Save” feature is
selected, this will also compiler/build project files.
* SQL is not included with MPLAB X IDE and must be acquired separately.

TABLE 6-9: TERMINAL FUNCTIONS

Function Details
org-netbeans-modules-dlight- Opens the Terminal window.
terminal-action-LocalTerminal()
org-netbeans-modules-dlight- Opens the Remote Terminal window.
terminal-action-RemoteTerminal()

TABLE 6-10: TOOLS FUNCTIONS

Function Details
Check CVS Select CVS version control items. For more on CVS,
see http://www.nongnu.org/cvs.

 2011-2012 Microchip Technology Inc. DS52027B-page 129

MPLAB® X IDE User’s Guide
TABLE 6-11: VIEW FUNCTIONS
Function Details
Web Browser Opens the NetBeans download page in your default
browser.
IDE Log Opens the IDE log file in the Output window.
To set up a log file, go to Tools>Options
(mplab_ide>Preferences for Mac OSX), Embedded
button, Generic Settings tab.
Classes Opens the Classes window.
Customize Zoom Threads/Profiles: Customize zoom on data.
Zoom In Threads/Profiles: Zoom in on data.
Zoom Out Threads/Profiles: Zoom out on data.

TABLE 6-12: WINDOW FUNCTIONS

Function Details
Debug>Breakpoints Opens the Breakpoints window.
Debug>Call Stack Opens the Call Stack window.
Debug>Variables Opens the Variables window.
Debug>Sessions Opens the Sessions window.
Debug>Sources Opens the Sources window.
Debug>Threads Opens the Threads window.
This window lists all threads in the current debugging session.
Debug>Watches Opens the Watches window.
Select Document In>Select Opens Favorites window and selects current document within
In Favorites it.
Terminal Opens the Terminal window.
Remote Terminal Opens the Remote Terminal window.
Terminal (Experimental) Opens the Experimental Terminal window.
Stopwatch Opens the Stopwatch window.
Trace Opens the Trace window.
Disassembly Listing File Opens the disassembly listing file in an editor window.
Project Environment Opens the Project Environment (Dashboard) window.
Analyzer Opens the Simulator Analyzer window.
Stimulus Opens the Simulator Stimulus window.
Services Opens the Services window.
Output Opens the Output window.
Properties Opens the Project Properties window.
Call Graph Opens the Call Graph window.
Hierarchy View Opens the Include Hierarchy window.
This lets you inspect all header and source files that are
directly or indirectly included in a source file, or all source and
header files that directly or indirectly include a header file.
Macro Expansion View Opens the Macro Expansion window.
This window expands macros in code.
Thread Map Opens the Threads window.
Reporter Result Opens the Exception Reporter window for exception break-
points.
Favorites Opens the Favorites window.
Test Results Opens the unit Test Results window for C/C++ projects.

DS52027B-page 130  2011-2012 Microchip Technology Inc.

 Advanced Tasks
TABLE 6-12: WINDOW FUNCTIONS (CONTINUED)
Function Details
Chat Opens a Team Chat window.
Team Opens a team project. For more on team server projects, see
NetBeans help, “IDE Basics>Collaborative Development”.
Navigator Opens the Navigator window.
Palette Opens the Palette window. (Java related)
Find Usages Results Opens the Find Usages window.
Refactoring Preview Opens a Preview window of refactoring results.
Search Results Opens the Search window.
Tasks Opens the Tasks window.

TABLE 6-13: XML FUNCTIONS

Function Details
Check File Checks an XML file for well-formedness.
Check DTD Opens the DTDs and XML Schemas Manager.
Validate File Checks an XML file for syntax errors in accordance with
an XML schema or DTD.
XSL Transform Transform XML document(s) using an XSL stylesheet.

 2011-2012 Microchip Technology Inc. DS52027B-page 131

MPLAB® X IDE User’s Guide
NOTES:

DS52027B-page 132  2011-2012 Microchip Technology Inc.

 MPLAB® X IDE
USER’S GUIDE
Chapter 7. Editor
7.1 INTRODUCTION
MPLAB X IDE is built upon the NetBeans platform, which provides a built-in editor to
create new code or change existing code.
General information on this editor is available under the NetBeans help topic IDE
Basics>Basic File Features. C compiler information regarding the editor is available
under the NetBeans help topic C/C++/Fortran Development>Working with C/C++/
Fortran Projects>Editing Source Files in C/C++/Fortran Projects>About Editing C and
C++ Files. MPLAB X IDE Editor features are discussed below.
• Editor Usage
• Editor Options
• Editor Features of Note
• Code Folding
• C Code Refactoring

7.2 EDITOR USAGE

The following desktop items are associated with the Editor:
• File menu (see Section 10.2.1 “File Menu”) to open a file in an Editor window.
• Edit menu (see Section 10.2.2 “Edit Menu”) to use edit commands.
• Editor toolbar located at the top of each file’s Editor window (see
Section 10.3.9 “Editor Toolbar”) to access some edit commands.
• Window right click (context) menu for additional commands.

7.3 EDITOR OPTIONS

To set editor options:
1. Select Tools>Options (mplab_ide>Preferences for Mac OSX) to open the
Options dialog.
2. Click on the Editor button. Then click on a tab to set up a editor features.
NetBeans Editor options may be found at Options Window: Editor.
For MPLAB X IDE, each tab and its options are listed below.

TABLE 7-1: GENERAL TAB

Item Description
Code Folding Check to enable Code Folding and select which types of code to
fold. For more on Code Folding see Section 7.5 “Code Folding”.
Camel Case Behavior Check to enable camel case navigation.

 2011 Microchip Technology Inc. DS52027A-page 133

MPLAB® X IDE User’s Guide
TABLE 7-2: FORMATTING TAB
Item Description
Language Select the programming language to which the formatting will apply.
Category Select a category, currently only “Tabs and Indents”.
Expand Tabs to Spaces Check to make tabs into spaces.
Number of Spaces per Enter the equivalent number of spaces per indent.
Indent
Tab Size Enter the size of a tab.
Right Margin Enter the size of the right margin.

TABLE 7-3: CODE COMPLETION TAB

Item Description
Language Select the programming language to which code completion will apply.
Completion options Check to enable code completion options. For more on code
completion, see the NetBeans help topic C/C++/Fortran
Development>Working with C/C++/Fortran Projects>Editing Source
Files in C/C++/Fortran Projects>Using Code Completion

TABLE 7-4: CODE TEMPLATES TAB

Item Description
Language Select the programming language to which the template will apply.
Templates Enter template information for the language specified above.
Abbreviation: Enter an abbreviation to type into the editor.
Expanded Text: After typing the abbreviation and the “Expand template
on” character(s), expand the abbreviation to this text in the editor.
Description: Add an optional description of the template item.
For more on code templates, see the NetBeans help topic
C/C++/Fortran Development>Working with C/C++/Fortran
Projects>Editing Source Files in C/C++/Fortran Projects>Using Code
Templates
Expand template on Select character(s) that will be typed into the editor to expand the
abbreviated text to the expanded text.

TABLE 7-5: HINTS TAB

Item Description
Language Select the programming language to which the hints will apply.
Hint Window In the Hint window, select an occurrence and specify the “hint” you wish to
receive in the event of the occurrence: Error, Warning or Warning on
current line.

TABLE 7-6: MACROS TAB

Item Description
Macros Add, delete and define editor macros.
New: Add the new named macro.
Set Shortcut: Enter a keystroke shortcut for the macro. If this keystroke has
already in use, red text in the dialog will announce this.
Remove: Click on the marco name and then click Remove to delete the macro.

DS52027A-page 134  2011 Microchip Technology Inc.

 Editor
TABLE 7-6: MACROS TAB (CONTINUED)
Item Description
Macro Code Click on the marco name above and then type in your macro code.
Note: It is generally easier to add a new macro by recording it than by adding
one manually in the Macro Code editor. Use Edit>Start/Stop Macro Recording.

7.4 EDITOR FEATURES OF NOTE

The following table summarizes some of the more frequently-used features of the
editor.

Editor Feature Reference

Unicode is supported. IDE Basics>Configuring the IDE>About Project Encod-
ings
Code is colored based on syntax. Tools>Options (mplab_ide>Preferences for Mac OSX),
Fonts and Colors button, Syntax tab.
Based on Encoding set during Project creation.
Errors are flagged as code is typed. C/C++/Fortran Development>Working with
C/C++/Fortran Projects>Editing Source Files in
C/C++/Fortran Projects>Error Highlighting
Colored markers provide quick Tools>Options (mplab_ide>Preferences for Mac OSX),
access to multiple symbols, errors, Fonts and Colors button, Annotations tab
etc.
Smart code completion makes sug- Tools>Options (mplab_ide>Preferences for Mac OSX),
gestions and provides hints. Editor button, Code Completion tab
Assembly and C code may be col- Section 7.5 “Code Folding”
lapsed and expanded.
Right clicking on a function Find Usages dialog
(delay(x)) finds usages. This can
limit find within a function. (e.g., a
local i variable).
Right clicking on a function Section 5.14 “View The Call Graph”
(delay(x)) shows a call graph. The
call graph has buttons on the side to
switch order, etc.
Create comments with task keywords IDE Basics>Basic File Features>Working with Task
(example: //TODO) in the source Lists
code and tasks will be scanned and
added automatically to the Task win-
dow.
File history is available to view recent Section 5.17 “Control Source Code” – local history
changes and revert, even without a
version control system.
Navigation is simplified with items Section 10.2.4 “Navigate Menu”
such as “Go to file”, “Go to type”, “Go
to symbol”, “Go to header”, and “Go
to declaration”.
Refactor options (rename functions Section 7.6 “C Code Refactoring”
and variables, find all functions, etc.)
for improving code structure.

 2011 Microchip Technology Inc. DS52027A-page 135

MPLAB® X IDE User’s Guide

7.5 CODE FOLDING

Code folding allows you to hide some sections of code so you may focus on others.
Sections of assembly or C code may be collapsed (hidden) or expanded (displayed)
depending on your selected options.
• Enable and Set Up Code Folding
• Custom Cold Folding - C
• Custom Cold Folding - ASM
• Expand/Collapse Cold Folding

7.5.1 Enable and Set Up Code Folding

To enable and set up cold folding:
1. Select Tools>Options (mplab_ide>Preferences for Mac OSX) to open the
Options dialog.
2. Click on the Editor button.
3. Click on the General tab and check “Use code folding”.
4. Check other options to specify sections to fold. If you do not see the type of code
you wish to fold listed here, you can do a custom fold as described next.

7.5.2 Custom Cold Folding - C

To custom fold C code, do the following:
• Type the following comments around your code:
// <editor-fold defaultstate="collapsed" desc="user-description">
C code block to fold
// </editor-fold>
OR
• Type fcom and then hit the <Tab> key to automatically enter the comment text
above.
Once the comment has been entered, you may customize it for your code:

defaultstate Enter either collapsed or expanded,

desc Enter a description of the code. Once collapsed, this description can
still be seen for reference.

An example of custom code folding is shown below.

DS52027A-page 136  2011 Microchip Technology Inc.

 Editor
FIGURE 7-1: EXPANDED CODE

FIGURE 7-2: COLLAPSED CODE

For additional information see the NetBeans help topic C/C++/Fortran

Development>Working with C/C++/Fortran Projects>Editing Source Files in
C/C++/Fortran Projects>Folding Blocks of Code.

7.5.3 Custom Cold Folding - ASM

To custom fold assembly code, do the following:
• For MPASM assembler or MPLAB XC16 assembler code, type the following
comments around your code:
; <editor-fold defaultstate="collapsed" desc="user-description">
ASM code block to fold
; </editor-fold>
• For MPLAB XC32 assembler code, type the following comments around your
code:
// <editor-fold defaultstate="collapsed" desc="user-description">
ASM code block to fold
// </editor-fold>
OR
• For MPASM assembler or MPLAB XC16 assembler code, type fcom; and then
hit the <Tab> key to automatically enter the relevant comment text above.
• For MPLAB XC32 assembler code, type fcom// and then hit the <Tab> key to
automatically enter the relevant comment text above.
Assembly code will fold in the same way as C code. For an example of code folding,
see the C code example above.

 2011 Microchip Technology Inc. DS52027A-page 137

MPLAB® X IDE User’s Guide

7.5.4 Expand/Collapse Cold Folding

To expand/collapse code blocks, go to the View menu or right-click in the Editor window
and select:
1. Code Folds>Collapse Fold to hide the block of code.
2. Code Folds>Expand Fold to display the block of code.
3. Code Folds>Collapse All to hide all folding blocks of code.
4. Code Folds>Expand All to display all folding the block of code.

DS52027A-page 138  2011 Microchip Technology Inc.

 Editor

7.6 C CODE REFACTORING

Note: To see this feature, refer to the Start Page, My MPLAB IDE tab, “Extend
MPLAB” section, “Selecting Simple or Full-Featured Menus” topic.
Refactoring is the use of small transformations to restructure code without changing
any program behavior. Just as you factor an expression to make it easier to understand
or modify, you refactor code to make it easier to read, simpler to understand, and faster
to update. And just as a refactored expression must produce the same result, the
refactored program must be functionally equivalent with the original source.
Some common motivations for refactoring code include:
• Making the code easier to change or easier to add a new feature
• Reducing complexity for better understanding
• Removing unnecessary repetition
• Enabling use of the code for other needs or more general needs
• Improving the performance of your code
The IDE’s refactoring features simplify code restructuring by evaluating the changes
that you want to make, showing you the parts of your application that are affected, and
making all necessary changes to your code. For example, if you use the Rename oper-
ation to change a class name, the IDE finds every usage of that name in your code and
offers to change each occurrence of that name for you.
• Refactor Menu
• Undoing Refactoring Changes
• Finding Function Usages
• Renaming a Function or Parameter
• Moving, Copying and Safely Deleting C Code

7.6.1 Refactor Menu

When you use the IDE’s refactoring operations, you can change the structure of your
code and have the rest of your code updated to reflect the changes you have made.
Refactoring operations are available on the Refactor menu (see
Section 10.2.6 “Refactor Menu”).

7.6.2 Undoing Refactoring Changes

You can undo any changes that you made using the commands in the Refactor menu
by following the steps below. When you undo a refactoring, the IDE rolls back all the
changes in all the files that were affected by the refactoring.
To undo a refactoring command:
1. Go to the Refactor menu in the main menu bar.
2. Choose Undo.
The IDE rolls back all the changes in all the files that were affected by the
refactoring.
If any of the affected files have been modified since the refactoring took place, the
Refactoring Undo is not available.

 2011 Microchip Technology Inc. DS52027A-page 139

MPLAB® X IDE User’s Guide

7.6.3 Finding Function Usages

You can use the Find Usages command to determine everywhere a function is used in
your project’s source code.
To find where a function is used in your project:
1. In the Navigator window or the Source Editor window, right click the function
name and choose Find Usages (Alt-F7).
2. The Find Usages command displays the code lines that call the function. In the
Find Usages dialog box, click Find.
The Usages window displays the file name and the line of code for each usage
found in that file.
To jump to a specific occurrence of the function, do one of the following actions:
• In the Usages window, use the up and down arrow buttons in the left pane to
navigate from one occurrence of the function to the next.
• Double click a line of code to open the file and to position the cursor on that line of
code.

Additional IDE Find Mechanisms

The other IDE tools that enable you to search for all the places where specific text is
used in a project include:
• Finding and Replacing Text. Searches for all the places where specific text is
used in a source file that is open in the Editor. Choose Edit>Find to open the Find
dialog box, or choose Edit>Replace to open the Replace dialog box. These com-
mands finds all matching strings, regardless of whether the string is a C code
element.
• Find in Projects. As with the Find command, the Find in Projects command
searches for matching strings, regardless of whether the string is a function name.
Choose Edit>Find in Projects to open the “Find in Projects” dialog box and then
type the string of text that you are looking for.
To find where a function is declared in a source file, you can double click the function
in the Navigator window. If the function is declared in a different source file, right click
the function and choose Navigate>Go To Declaration from the contextual menu.

7.6.4 Renaming a Function or Parameter

To rename a function or parameter and update references to it throughout your project:
1. In the Source Editor, right click the function or parameter and choose
Refactor>Rename from the contextual menu.
2. In the Rename dialog box, type the New Name.
3. Optionally, click Preview. In the Refactoring window, at the bottom of the Source
Editor, review the lines of code that will be changed and clear the checkbox of
any code that you do not want changed.
4. Click Do Refactoring to apply the selected changes.
For quick in-place renaming, place the cursor in the item that you want to rename, and
press Ctrl-R. Then type the new name. To finish renaming, press Escape.

7.6.5 Moving, Copying and Safely Deleting C Code

These functions are specific to C++ code. See Section 10.2.6 “Refactor Menu”.

DS52027A-page 140  2011 Microchip Technology Inc.

 MPLAB® X IDE
USER’S GUIDE
Chapter 8. Troubleshooting
8.1 INTRODUCTION
This section is designed to help you troubleshoot any problems, errors or issues you
encounter while using MPLAB X IDE. If none of this information helps you, please see
“Support” for ways to contact Microchip Technology.
• USB Driver Installation Issues
• Cross-Platform Issues
• MPLAB X IDE Issues
• NetBeans Platform Issues
• Errors
• Forums

8.2 USB DRIVER INSTALLATION ISSUES

To install the correct USB drivers, see Section 2.3 “Install the USB Device Drivers
(For Hardware Tools)”.
To troubleshoot errors, see Section 2.3.2.6 “Tool Communication Issues”.

8.3 CROSS-PLATFORM ISSUES

If you plan on using MPLAB X IDE on different platforms (Windows, Mac, Linux OS),
be aware of these issues:
• Use the forward slash “/” in relative paths. The backslash “\” works only on
Windows OS platforms. Example: #include headers/myheader.h.
• Linux OS is case-sensitive, so generictypedefs.h is not the same as
GenericTypeDefs.h.

 2011-2012 Microchip Technology Inc. DS52027A1-page 141

MPLAB® X IDE User’s Guide

8.4 MPLAB X IDE ISSUES

Importing an MPLAB IDE v8 Project - Settings
Settings that were saved in a workspace in MPLAB IDE v8 (such as tool settings) will
not be transferred to the new MPLAB X IDE project. Refer to the MPLAB IDE v8 help
for what is stored in a workspace (MPLAB IDE Reference>Operational
Reference>Saved Information.)

Importing an MPLAB IDE v8 Project - Modified Linker Scripts

If you have modified your MPLAB IDE v8 project linker script so that it includes an
object file, the linker will be unable to find the file when imported into MPLAB X IDE
because the build paths for MPLAB IDE v8 and MPLAB X IDE are different.
So you may see an error like:
<install path>ld.exe: cannot find file.o
since in MPLAB IDE v8 all build-related files are in one directory, whereas in MPLAB X
IDE build files are in different subdirectories.
You can edit your linker script to work with MPLAB X IDE by using wild cards.
For example, change:
/* Global-namespace object initialization - MPLAB v8*/
.init :
{
KEEP (crti.o(.init))
:
} >kseg0_program_mem
to:
/* Global-namespace object initialization - MPLAB X*/
.init :
{
KEEP (*crti.o(.init))
:
} >kseg0_program_mem
Alternatively, you can use an address attribute that allows you to place functions in C
code.
int __attribute__((address(0x9D001000))) myfunction (void) {}
This allows you to place a function at an address without modifying the default linker
script.

DS52027A1-page 142  2011-2012 Microchip Technology Inc.

 Troubleshooting

8.5 NETBEANS PLATFORM ISSUES

The NetBeans platform may have issues concerning the platform release used for
MPLAB X IDE. For more help, visit the NetBeans web site (www.netbeans.org).
See also:
http://netbeans.org/community/releases/index.html

8.6 ERRORS
Errors can take many forms in the IDE, most commonly as icons in windows or mes-
sages in the Output window. Hovering over icons will pop up text that may explain the
issue. For text messages, please refer to online help to search for the error.
Some errors are listed below.

Command line too long (Windows XP and above OS)

When a project’s makefile is run, each command that is executed is passed to the local
native shell. For Windows XP and above OS, there is a limit of 8191 characters. For
Linux and Mac OS X, the limit is over 100K. Therefore, for a Windows XP and above
OS and for a project with hundreds of c files that link, the limit could be surpassed and
this warning will be displayed.
Response File Workaround
If you are using either the MPLAB XC32 C compiler or MPLAB XC8 C compiler v1.01
and above, you may be able to use a response file when calling the linker to work
around this issue.
For MPLAB XC8, in the Project Properties window (File>Project Properties), click in
“Categories” on “XC8 linker”. Under “Option categories” select “Additional Options”.
Check the checkbox next to “Use response file to link”.
For MPLAB XC32, in the Project Properties window (File>Project Properties), click in
“Categories” on “xc32-ld”. Under “Option categories” select “General”. Check the
checkbox next to “Use response file to link”.
Library Workaround
For all other compilers, you can create an MPLAB X IDE library project and move some
source files from your main project to the library project. Then add the library project to
your main project.
To create a library project select File>New Project, click the “Microchip Embedded”
category, and then select “Library project” as the project.
To add the library to your main project, open the Project Properties window (File>
Project Properties), click in “Categories” under “Libraries”, and then click the “Add
Library Project” button.

 2011-2012 Microchip Technology Inc. DS52027A1-page 143

MPLAB® X IDE User’s Guide

Couldn’t reserve space for cygwin’s heap (Windows 7 OS)

MPLAB X IDE uses the Cygwin MinGW in its make process. In Windows 7, you may
have virtual memory allocation issues.
To change the Virtual Memory settings, click Start>Control Panel. Then click System
and then Security>System>Advanced Systems Setting or System Protection. On the
Advanced tab, click on the Performance Settings button. In this dialog click the
Advanced tab and then click on the Change button. Enter a custom size value as
follows:
• Initial Size (MB) = Currently Allocated (shown at the bottom)
• Maximum Size (MB) = Recommended (shown at the bottom)
Click Set, click OK and reboot your personal computer.

Could not access the URL through the external browser. Check the
browser configuration
In MPLAB X IDE, select Tools>Options, General Tab. In the “Web Browser” drop-down
list, select your browser. Click OK.
For more information see:
http://netbeans.org/bugzilla/show_bug.cgi?id=21236
http://netbeans.org/bugzilla/show_bug.cgi?id=38211
http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4646857

8.7 FORUMS
If you do not see your issue here, check out our forums at:
http://www.microchip.com/forums/f238.aspx
Here you will find discussions and recently posted solutions to problems.

DS52027A1-page 144  2011-2012 Microchip Technology Inc.

 MPLAB® X IDE
USER’S GUIDE
Chapter 9. MPLAB X IDE vs. MPLAB IDE v8
9.1 INTRODUCTION
MPLAB X IDE differs considerably from MPLAB IDE v8 and before. The topics in this
section will help you with migration issues.
• Major Differences
• Menu Differences
• Tool Support Differences

9.2 MAJOR DIFFERENCES

Because MPLAB X IDE is based on the NetBeans platform, many features will be dif-
ferent from MPLAB IDE v8. Please see the following for more detailed information:
• Section Chapter 2. “Before You Begin”
• Section Chapter 3. “Tutorial”
• Section Chapter 5. “Additional Tasks”
A short list of major feature differences is presented below:
1. MPLAB X IDE is based on the open-source, cross-platform NetBeans plat-
form. Third parties can easily add functionality as plug-ins. MPLAB X IDE
components that are specific to Microchip products are still proprietary.
MPLAB IDE v8 is proprietary and Windows based. Third parties can add to
v8 with design information from the MPLAB development group.
2. MPLAB X IDE is project-based (no workspaces). In MPLAB X IDE, you must
create a project to develop your application. Creating a project involves selecting
a device, as well as selecting and setting up language tools, debug tools, pro-
gramming tools and other project specifics. This ensures all items needed for
successfully developing an application are present. Multiple project grouping is
handled by multiple configurations.
MPLAB IDE v8 is device-based. Although it is always highly recommended that
you use a project in v8 to create your application, it is not required. Workspaces
are used to contain some set up information, including multi-project grouping.
As projects have changed significantly, reading Chapter 3. “Tutorial” is
recommended.
3. MPLAB X IDE allows multiple tool selection.
Example 1: Connect several MPLAB ICD 3 debuggers, with associated target
boards, into several USB ports on the computer. Then access the Project prop-
erties to easily switch between the debuggers, which are identified by their serial
numbers (SN).
Example 2: Connect one MPLAB ICD 3 debugger, with an associated target
board, and one MPLAB PM3 programmer into one USB port each. Then access
the Project properties to easily switch between the tools.
MPLAB IDE v8 does not allow multiple tool selection.

 2011-2012 Microchip Technology Inc. DS52027B-page 145

MPLAB® X IDE User’s Guide
4. MPLAB X IDE allows multiple language tool version selection
Example: Install two versions of the MPLAB C Compiler for PIC18 MCUs. Then
access the Project properties to easily switch between versions of compiler
toolchains.
MPLAB IDE v8 does not allow multiple language tool version selection.
5. MPLAB X IDE allows multiple debug and programming sessions. MPLAB X
IDE allows you may have multiple debug sessions active in one IDE. For more
information, see Section 6.2 “Multiple Projects”.
MPLAB IDE v8 allowed one debug or programming session. MPLAB IDE v8
allowed you to have multiple projects open in the IDE. However, you could only
debug or program with one project at a time.
6. MPLAB X IDE allows multiple build configurations. MPLAB X IDE allows
more than one build configuration. For more information, see
Section 6.3 “Multiple Configurations”.
MPLAB IDE v8 allowed only two configurations. MPLAB IDE v8 allowed you
to select only between “Release” or “Debug” from the Build Configuration
drop-down box and have use of __DEBUG in your own code.
To recreate the MPLAB IDE v8 functionality in MPLAB X IDE, you can create
your own Debug configuration and __DEBUG macro by following the example in
Section 6.3.2 “Add a Duplicate Configuration”.
7. MPLAB X IDE provides multi-step options to debug and program. MPLAB
X IDE has a “Debug Project” icon that builds, programs a target device with your
program and a debug executive (for hardware tools) and runs your code in
Debug mode in one click. Also available is a “Make and Program” icon that
builds, programs a target device (for hardware tools) and runs your code in one
click. If you do not want your program to run after make and program, use the
“Hold in Reset” icon instead.
MPLAB IDE v8 required several manual steps to debug or program. MPLAB
IDE v8 had a procedure that requires completion before debugging or running
code: (1) select the correct build configuration (Release or Debug), (2)
build/make your code, (3) program the target with the code (for hardware tools)
and (4) run your code.
For some tools, e.g., MPLAB Starter Kits, you still need to perform some steps
independently. MPLAB X IDE provides this functionality under Debug>Discrete
Debugger Operation.
8. MPLAB X IDE uses configuration bits set in code. MPLAB X IDE requires that
Configuration bits be set in code. However, you may temporarily change Config-
uration bits in the Configuration bits window when in a debug session and then
save these setting to a file to paste into your code later (see Section 4.22.4 “Set
Configuration Bits”.)
MPLAB IDE v8 used configuration bits set in code or a window. MPLAB IDE
v8 allowed you to set Configuration bits in either code or the Configuration bits
window. However, settings made in the window had to be manually entered into
code.

DS52027B-page 146  2011-2012 Microchip Technology Inc.

 MPLAB X IDE vs. MPLAB IDE v8
9. MPLAB X IDE debug tools are only connected during a session. MPLAB X
IDE only connects debug or programmer tools to the target during a debug or
programming session. Otherwise they are not connected.
MPLAB IDE v8 debug tools were always connected. MPLAB IDE v8 con-
nected to the debug and programmer tools as soon as the tool was selected. This
configuration did not allow for multiple sessions.
To maintain this connection at all times in MPLAB X IDE, like MPLAB IDE v8, go
to Tools>Options (mplab_ide>Preferences for Mac OSX), Embedded, Generic
Settings tab, and check “Maintain active connection to hardware tool”.
10. MPLAB X IDE information is consolidated in one display. MPLAB X IDE has
a Dashboard window that contains breakpoint resources, checksum and mem-
ory gauge information. See Section 5.15 “View the Dashboard Display”. This
window organizes this and future information in one place.
MPLAB IDE v8 information is spread over several displays. MPLAB IDE v8
had a breakpoint resources toolbar, checksum toolbar and memory gauge win-
dow. Each feature was accessed differently.
11. MPLAB X IDE has many NetBeans features. MPLAB X IDE has many Net-
Beans editing and debug features. (See NetBeans Help for more details.) Peri-
odically, MPLAB X IDE will update the NetBeans platform it is based upon. Then
the IDE will be updated to the new NetBeans features. The MPLAB X IDE
release notes will specify the NetBeans platform version that each version of
MPLAB X IDE is built upon.
MPLAB IDE v8 had its own, proprietary features. MPLAB IDE v8 was a pro-
prietary product. As such, third-party and community development was more
difficult.

 2011-2012 Microchip Technology Inc. DS52027B-page 147

MPLAB® X IDE User’s Guide

9.3 MENU DIFFERENCES

The following tables highlight the menu changes from MPLAB IDE v8 to MPLAB X IDE.
Due to the changes in MPLAB X IDE, not all MPLAB IDE v8 menu items will map
identically. Major differences are discussed under Comments.
Additional menu items may be available in MPLAB X IDE. See the table of contents for
the NetBeans help topic “IDE Basics” for details.

TABLE 9-1: FILE MENU DIFFERENCES

®
MPLAB IDE v8 MPLAB® X IDE Comments
New File>New File Select associated project in file
Add New File to Project wizard.
Open File>Open File
Close File>Close
Save File>Save
Save As File>Save As
Save All File>Save All
Open Workspace N/A All data saved in projects
Save Workspace N/A
Save Workspace As N/A
Close Workspace N/A
Import File>Import Useful for Hex Import
Export Right click on file in project in
Project tabbed window, select
‘Export Hex’
Print File>Print
File>Print to HTML
File>Page Setup
Recent Files File>Open Recent File
Recent Workspaces N/A All data saved in projects
Exit File>Exit

DS52027B-page 148  2011-2012 Microchip Technology Inc.

 MPLAB X IDE vs. MPLAB IDE v8
TABLE 9-2: EDIT MENU DIFFERENCES
®
MPLAB IDE v8 MPLAB® X IDE Comments
Undo Edit>Undo
Redo Edit>Redo
Cut Edit>Cut
Copy Edit>Copy
Paste Edit>Paste
Edit>Paste Formatted
Delete Edit>Delete
Select All Edit>Select All
Edit>Select Identifier
Find Edit>Find
Edit>Find Selection
Find Next Edit>Find Next
Edit>Find Previous
Find In Files Edit>Find in Projects
Edit>Replace in Projects
Replace Edit>Replace
Go To Navigate>Go to Line
Navigate>Go to Declaration
Go To Locator Navigate>Go to Symbol
Go Backward Navigate>Back
Go Forward Navigate>Forward
External DIFF Tools>Diff See also Tools>Options
(mplab_ide>Preferences for
Mac OSX), Miscellaneous, Diff
tab
Advanced Source>Format
Source>Shift Left/Right
Source>Move Up/Down
Source>Toggle Comment
Bookmarks Navigate>Toggle Bookmark
Navigate>Next Bookmark
Navigate>Previous Bookmark
Properties Tools>Options>Editor tab Use mplab_ide>Preferences
Tools>Options>Fonts & Colors instead of Tools>Options for
Mac OSX.

 2011-2012 Microchip Technology Inc. DS52027B-page 149

MPLAB® X IDE User’s Guide
TABLE 9-3: VIEW MENU DIFFERENCES
®
MPLAB IDE v8 MPLAB® X IDE Comments
Project Window>Projects
Output Window>Output>Output
Toolbars View>Toolbars
CPU Registers* Window>PIC Memory
Views>CPU
Call Stack Window>Debugging>Call Stack
Disassembly Listing Window>Output>Disassembly
Listing File
EEPROM Window>PIC Memory Customize in window
Views>EE Data Memory
File Registers Window>PIC Memory
Views>Data Memory
Flash Data Window>PIC Memory
Views>Data Memory
Hardware Stack Debug>Stack
LCD Pixel Not yet available
Locals Window>Debugging>Variables
Memory* Window>PIC Memory Customize in window
Views>Other Memory
Program Memory Window>PIC Memory
Views>Flash Memory
SFR/Peripherals* Window>PIC Memory
Views>Peripherals
Special Function Regis- Window>PIC Memory
ters Views>SFRs
Watch Window>Debugging>Watches See also:
Debug>New Watch
Memory Usage Gauge Window>Dashboard Memory usage is in the PE
window
Trace Window>Debugging>Trace See also:
File>Project Properties
to enable trace
* PIC32 MCUs Only

DS52027B-page 150  2011-2012 Microchip Technology Inc.

 MPLAB X IDE vs. MPLAB IDE v8
TABLE 9-4: PROJECT MENU DIFFERENCES
®
MPLAB IDE v8 MPLAB® X IDE Comments
Project Wizard File>New Project Always invoked for new project
New File>New Project
Open File>Open Project
File>Open Recent Project
Close File>Close Project
Set Active Project Run>Set Main Project
Quickbuild N/A A project is required for all
development.
Package in .zip Right click on project in Project
tabbed window, select ‘Package’
Clean Right click on project in Project
tabbed window, select ‘Clean
and Build’
Locate Headers N/A
Export Makefile Not yet available.
Build All Run>Run Project Programmer build/run
Make Debug>Debug Project Debug build/run
Build Configuration File>Project Group There used to be only two con-
Run>Set Project Configuration figurations: Release and Debug.
Now you determine how many
you need.
Build Options File>Project Properties Language tool set up
Save Project File>Save
File>Save All
Save Project As File>Save As
Add Files to Project Right click on folder in project in
Project tabbed window, select
‘Add Existing Item’
Add New File to Project File>New File
Remove File from Project Right click on file in project in
Project tabbed window, select
‘Remove From Project’
Select Language File>Project Properties
Toolsuite
Set Language Tool Loca- Tools>Options, Embedded Use mplab_ide>Preferences
tions instead of Tools>Options for
Mac OSX.
Version Control Tools>Options, Miscellaneous, Use mplab_ide>Preferences
Versioning tab instead of Tools>Options for
Mac OSX.
See also Team menu,
Window>Versioning

 2011-2012 Microchip Technology Inc. DS52027B-page 151

MPLAB® X IDE User’s Guide
TABLE 9-5: DEBUGGER MENU DIFFERENCES
®
MPLAB IDE v8 MPLAB® X IDE Comments
Select Tool File>New Project To select
File>Project Properties To change
Clear Memory TBD Used by Programmers
Run Run>Run Project Programmer Run
Debug>Debug Project Debug Run
Debug>Continue Run from Halt
Animate N/A
Halt Debug>Pause
Step Into Debug>Step Into
Step Over Debug>Step Over
Step Out Debug>Step Out
Reset Debug>Reset
Breakpoints Debug>New Breakpoint
Debug>Toggle Breakpoint
Settings File>Project Properties
Stopwatch Window>Debugging>Stopwatch

TABLE 9-6: PROGRAMMER MENU DIFFERENCES

MPLAB® IDE v8 MPLAB® X IDE Comments
Select Programmer File>New Project To select
File>Project Properties To change
Enable Programmer N/A Once selected, it is enabled.
Disable Programmer
Program Program Target Project On Run toolbar
Verify Not available See the MPLAB IPE
Read Upload Target Project On Run toolbar
Blank Check All Not available See the MPLAB IPE
Blank Check OTP Not available See the MPLAB IPE
Erase Flash Device Available on custom toolbar See Section 6.5 “Customize
Toolbars”
Reset Program Statistics Not yet available.
Download OS File>Project Properties, debug The IDE will automatically
tool category, Firmware option choose the most up-to-date firm-
ware to download
Settings File>Project Properties

TABLE 9-7: TOOLS MENU DIFFERENCES

MPLAB® IDE v8 MPLAB® X IDE Comments
Data Monitor and Con- Tools>Plugins To install
trol Interface (DMCI) and Tools>Embedded To use
other plugins
MPLAB® Macros Edit>Start Macro Recording
Edit>Stop Macro Recording
RTOS Viewer Tools>Plugins To install
Tools>Embedded To use

DS52027B-page 152  2011-2012 Microchip Technology Inc.

 MPLAB X IDE vs. MPLAB IDE v8
TABLE 9-8: CONFIGURE MENU DIFFERENCES
®
MPLAB IDE v8 MPLAB® X IDE Comments
Select Device File>New Project To select
File>Project Properties To change
Configuration Bits Window>PIC Memory
Views>Configuration Bits
External Memory Window>PIC Memory Customize in window
Views>Other Memory
ID Memory Window>PIC Memory Customize in window
Views>Other Memory
Settings Tools>Options Use mplab_ide>Preferences
instead of Tools>Options for
Mac OSX.

TABLE 9-9: WINDOW MENU DIFFERENCES

MPLAB® IDE v8 MPLAB® X IDE Comments
Close All Window>Close All Documents
Cascade Not supported. For document management, see
Tile Horizontally Window>Documents.
Tile Vertically
Arrange Icons
Window Sets
Create Window Set
Destroy Window Set
Recent Windows

TABLE 9-10: HELP MENU DIFFERENCES

MPLAB® IDE v8 MPLAB® X IDE Comments
Topics Help>Contents To view PDFs, see
Section 13.2 “Projects Win-
dow View”.
Release Notes Help>Online Docs and
Support
Driver Installation Help>Online Docs and
Support
Check for Updates Not available Please check the Microchip
website for updates
Web Links Help>Online Docs and
Support
About MPLAB® IDE Help>About

 2011-2012 Microchip Technology Inc. DS52027B-page 153

MPLAB® X IDE User’s Guide

9.4 TOOL SUPPORT DIFFERENCES

The following table lists the available Microchip development tools and whether or not
they will be supported in MPLAB X IDE.

TABLE 9-11: TOOL SUPPORT DIFFERENCES

In MPLAB® X IDE?
Development Tool
Yes No
PICkit™ 3 X
PICkit™ 2 X
PICkit™ 1 X
MPLAB® ICD 3 X
MPLAB® ICD 2 X
MPLAB® REAL ICE™ in-circuit emulator X
MPLAB® ICE 2000 X
MPLAB® ICE 4000 X
MPLAB® PM3 X
PRO MATE II X
PICSTART® Plus X
MPLAB® VDI X

TABLE 9-12: PLUGIN SUPPORT DIFFERENCES

In MPLAB® X IDE?
Plug-Ins
Yes No
DMCI X
dsPIC® Filter Design X
dsPIC30F SMPS Buck Converter X
dsPIC33F SMPS Buck/Boost Converter* X
dsPIC® Works X
Graphical Display Designer X
MATLAB® X
Memory Starter Kit X
PC-Lint X
RTOS Viewer X
Segmented Display Designer* X
AN851 Bootloader X
AN901 BLDC Tuning Interface X
AN908 ACIM Tuning Interface X
KEELOQ® Plugin X
* Under development

DS52027B-page 154  2011-2012 Microchip Technology Inc.

 MPLAB® X IDE
USER’S GUIDE
Chapter 10. Desktop Reference
10.1 INTRODUCTION
The MPLAB X IDE desktop is a resizable window that operates independent of the rest
of the desktop items. The desktop consists of menus, toolbars, a status bar and tabbed
windows (Figure 10-1). Menus, toolbars and the status bar are discussed here.
Windows and dialogs are discussed in their own section.

Note: When the NetBeans help topic refers to a workspace, it is talking about a
desktop. It is not referring to the MPLAB IDE v8 and earlier workspace.
• Menus
• Toolbars
• Status Bar
• Grayed-out or Missing Items and Buttons

FIGURE 10-1: MPLAB IDE DESKTOP

WINDOWS MENUS TOOLBARS

STATUS BAR

 2011-2012 Microchip Technology Inc. DS52027B-page 155

MPLAB® X IDE User’s Guide

10.2 MENUS
Many MPLAB IDE functions are accessible as menu items through the menu bar
located across the top of the desktop. Menu items followed by ellipses (...) will open a
dialog. For more on dialogs, see Chapter 11. “MPLAB X IDE Windows and Dialogs”.
Shortcut keys for menu items are listed next to the menu item. Example: The shortcut
keys for “New File” are Control-N (CTRL+N). More shortcut key information is available
in the NetBeans help topic under “IDE Basics>Keyboard Shortcuts”.
Menu items may be grayed-out for various reasons. See Section 10.5 “Grayed-out or
Missing Items and Buttons”.
Additional context menus are available by right clicking in a window. For more on these
menus, see Section 11.2.7 “Projects Window”.
Available menus are listed below.

Note: See the Start Page, My MPLAB IDE>Extend MPLAB>Selecting Simple or

Full-Featured Menus to see all available menus and menu items. Not all of
these items will be applicable to embedded development.

• File Menu
• Edit Menu
• View Menu
• Navigate Menu
• Source Menu
• Refactor Menu
• Run Menu
• Debug Menu
• Team Menu
• Tools Menu
• Window Menu
• Help Menu

10.2.1 File Menu

Below are the menu items in the File menu.
For keyboard shortcuts of some of these menu items, see the NetBeans help topic
IDE Basics>Keyboard Shortcuts>Menu Shortcuts.

TABLE 10-1: FILE MENU OPTIONS

Command Action
New Project Creates a new project with the New Project wizard.
New File Creates a new file with the New File wizard.
Open Project Opens an existing project.
Open Recent Project Displays a list of all recently-opened projects for selection.
Import Import one of the following:
Hex/ELF... (Prebuilt) File – Built with another tool
MPLAB IDE v8 Project – Launch Import Legacy Project
wizard
Open Team Project Opens a team project. For more on team server projects, see
NetBeans help, “IDE Basics>Collaborative Development”.
Close Project Closes the current project.
Close All Projects Closes all open projects.

DS52027B-page 156  2011-2012 Microchip Technology Inc.

 Desktop Reference
TABLE 10-1: FILE MENU OPTIONS (CONTINUED)
Command Action
Open File Opens an existing file.
Open Recent File Displays a list of all recently-opened files for selection.
Project Group Associates the current project with a group.
Project Properties Opens the Project Properties dialog.
Save Saves the current file.
Save As Saves the current file under a new path and/or name.
Save All Saves all open files. If the “Compile on Save” feature is
selected, this will also compiler/build project files.
Page Setup Sets up the page for printing.
Print Shows print preview of current file and allows printing.
Print to HTML Prints the current file to a new file in HTML format.
Exit Quits MPLAB® IDE.

10.2.2 Edit Menu

Below are the menu items in the Edit menu.
For keyboard shortcuts of some of these menu items, see the NetBeans help topic
IDE Basics>Keyboard Shortcuts>Menu Shortcuts.

TABLE 10-2: EDIT MENU OPTIONS

Command Action
Undo Reverses (one at a time) a series of editor actions, except
Save.
Redo Reverses (one at a time) a series of Undo commands.
Cut Deletes the current selection and places it on the clipboard.
Copy Copies the current selection to the clipboard.
Paste Pastes the contents of the clipboard into the insertion point.
Paste Formatted Pastes the formatted contents of the clipboard into the inser-
tion point.
Delete Deletes the current selection.
Select All Selects everything in the current document or window.
Select Identifier Selects the word nearest the cursor.
Find Selection Finds instances of the current selection.
Find Next Finds next instance of found text.
Find Previous Finds previous instance of found text.
Find Finds a text string.
Replace Finds a string of text and replaces it with the string specified.
Find Usages Finds usages and subtypes of selected code.
Find in Projects Finds specified text, object names, object types within proj-
ects.
Replace in Projects Replaces text, object names, object types within projects.
Start Macro Recording Start recording keystrokes.
Stop Macro Recording Stop recording keystrokes. To manage macros, select
Tools>Options, Editor button, Macros tab.

 2011-2012 Microchip Technology Inc. DS52027B-page 157

MPLAB® X IDE User’s Guide

10.2.3 View Menu

Below are the menu items in the View menu.
For keyboard shortcuts of some of these menu items, see the table of contents for the
NetBeans help topic IDE Basics>Keyboard Shortcuts>Menu Shortcuts.

TABLE 10-3: VIEW MENU OPTIONS

Command Action
Editors Select an available editor to view your files.
Code Folds>Collapse Fold If the insertion point is in a foldable section of text, collapses
those lines into one line.
Code Folds>Expand Fold If the currently selected line in the Source Editor represents
several folded lines, expands the fold to show all of the lines.
Code Folds>Collapse All Collapses all foldable sections of text in the Source Editor.
Code Folds>Expand All Expands all foldable sections of text in the Source Editor.
Web Browser Opens the default web browser to the NetBeans home page.
IDE Log Opens the MPLAB® IDE log file in a tab of the Output window.
Toolbars>File, etc. Shows the associated toolbar when selected (checked).
Toolbars>Small Toolbar Icons Uses small icons on the toolbars when selected (checked).
Toolbars>Reset Toolbars Resets to the default toolbar set up.
Toolbars>Customize Customizes the items on an existing toolbar and allows cre-
ation of a new one.
Show Editor Toolbar Shows the editor toolbar on the file tab when selected
(checked).
Show Line Numbers Shows line numbers when selected (checked).
Show Diff Sidebar Shows the DIFF sidebar when selected (checked).
Show Versioning Labels Shows versioning labels when selected (checked).
Synchronize Editor with Views Synchronizes the editor with open views when selected
(checked).
Show Profiler Metrics Shows the profiler metrics when selected (checked).
Full Screen Expand window to full length and breadth of screen.

10.2.4 Navigate Menu

Below are the menu items in the Navigate menu.
For keyboard shortcuts of some of these menu items, see the table of contents for the
NetBeans help topic IDE Basics>Keyboard Shortcuts>Menu Shortcuts.

TABLE 10-4: NAVIGATE MENU OPTIONS

Command Action
Go to File Finds and opens a specific file.
Go to Type Finds and opens a specific class or interface.
Go to Symbol Finds the symbol name as specified.
Go to Previous Document Opens the document last opened before the current one.
Go to Source Displays the source file containing the definition of the
selected class.
Go to Declaration Jumps to the declaration of the item under the cursor.
Go to Super Implementation Jumps to the super implementation of the item under the
cursor.
Last Edit Location Scrolls the editor to the last place where editing occurred.
Back Navigates back.

DS52027B-page 158  2011-2012 Microchip Technology Inc.

 Desktop Reference
TABLE 10-4: NAVIGATE MENU OPTIONS (CONTINUED)
Command Action
Forward Navigates forward.
Go to Line Jumps to the specified line.
Toggle Bookmark Sets a bookmark on a line of code.
Next Bookmark Cycles forward through the bookmarks.
Previous Bookmark Cycles backward through the bookmarks.
Next Error Scrolls the Source Editor to the line that contains the next
build error.
Previous Error Scrolls the Source Editor to the line that contains the previous
build error.
Select in Projects Opens Projects window and selects current document within
it.
Select in Files Opens Files window and selects current document within it.
Select in Classes Opens Classes window and selects current document within
it.
Select in Favorites Opens Favorites window and selects current document within
it.

10.2.5 Source Menu

Below are the menu items in the Source menu.
For keyboard shortcuts of some of these menu items, see the table of contents for the
NetBeans help topic IDE Basics>Keyboard Shortcuts>Menu Shortcuts.

TABLE 10-5: SOURCE MENU OPTIONS

Command Action
Format Formats the selected code or the entire file if nothing is
selected.
Remove Trailing Spaces Removed spaces at the end of the line.
Shift Left Moves the selected line or lines one tab to the left.
Shift Right Moves the selected line or lines one tab to the right.
Move Up Moves the selected line or lines one line up.
Move Down Moves the selected line or lines one line down.
Duplicate Up Copies the selected line or lines one line up.
Duplicate Down Copies the selected line or lines one line down.
Toggle Comment Toggles the commenting out of the current line or selected
lines.
Complete Code Shows the code completion box.
Insert Code Pops up a context aware menu that you can use to generate
common structures such as constructors, getters, and setters.
Fix Code Displays editor hints. The IDE informs you when a hint is avail-
able when the light bulb is displayed.
Show Method Parameters Selects the next parameter. You must have a parameter
selected (highlighted) for this shortcut to work.
Show Documentation Shows documentation for item under the cursor.
Insert Next Matching Word Generates the next word used elsewhere in your code as you
type its beginning characters.
Insert Previous Matching Generates the previous word used elsewhere in your code as
Word you type its beginning characters.
Scan for external changes Scans file for changes made outside of MPLAB® IDE.

 2011-2012 Microchip Technology Inc. DS52027B-page 159

MPLAB® X IDE User’s Guide

10.2.6 Refactor Menu

Below are the menu items in the Refactor menu. The items you see are dependant on
the type of object (variable, function, etc.) you are refactoring. For more information,
see Section 7.6 “C Code Refactoring”.
For keyboard shortcuts of some of these menu items, see the table of contents for the
NetBeans help topic IDE Basics>Keyboard Shortcuts>Menu Shortcuts.

TABLE 10-6: REFACTOR MENU OPTIONS

Command Action
Rename Enables you to change the name of a variable or function to
something more meaningful. In addition, it updates all source
code in your project to reference the element by its new name.
Move Moves a class to another package or into another class. In
addition, all source code in your project is updated to refer-
ence the class in its new location.
Copy Copies a class to the same or a different package.
Safely Delete Checks for references to a code element and then automati-
cally deletes that element if no other code references it.
Change Function Parameter Changes the amount and name of parameters for the selected
function.
Undo Un-does refactoring.
Redo Re-does refactoring.

10.2.7 Run Menu

Below are the menu items in the Run menu.
For keyboard shortcuts of some of these menu items, see the table of contents for the
NetBeans help topic IDE Basics>Keyboard Shortcuts>Menu Shortcuts.

TABLE 10-7: RUN MENU OPTIONS

Command Action
Run Project Runs the main or selected project.
Test Project Starts JUnit test for project. (Java related)
Build Project Build all the files in a project.
Clean and Build Project Remove (clean) previously generated project files and then
rebuild the files in a project.
Batch Build Project Build multiple configurations of a project. (Only embedded
available)
Set Project Configuration Selects project configuration. Should be “default”.
Set Main Project Set the main project by selecting from a list of open projects.
Run File Runs the currently selected file.
Test File Starts JUnit test for current file. (Java related)
Check File Check a file against a standard. (XML related)
Validate File Validate a file against a standard. (XML related)
Repeat Build/Run Run again after halt.
Stop Build/Run End run.

DS52027B-page 160  2011-2012 Microchip Technology Inc.

 Desktop Reference

10.2.8 Debug Menu

Below are the menu items in the Debug menu.
For keyboard shortcuts of some of these menu items, see the table of contents for the
NetBeans help topic IDE Basics>Keyboard Shortcuts>Menu Shortcuts.

TABLE 10-8: DEBUG MENU OPTIONS

Command Action
Debug Project Debugs the main or selected project.
Debug File Starts debugging session for currently selected file.
Debug Test File Starts debugging test for file in JUnit. (Java related)
Discrete Debugger Operation Performs debug operations one step at a time (discretely):
Build, Program Target, Launch Debugger.
This is useful for changing Memory window setting during
debug and using starter kits.
Finish Debugger Session Ends the debugging session.
Pause Pauses debugging. Use “Continue” to resume.
Continue Resumes debugging after “Pause” until the next breakpoint or
the end of the program is reached.
Step Over Executes one source line of a program. If the line is a function
call, executes the entire function and then stops.
Step Into Executes one source line of a program. If the line is a function
call, executes the program up to the function’s first statement
and then stops.
Step Instruction Executes one machine instruction. If the instruction is a func-
tion call, executes the function and returns control to the
caller.
Run to Cursor Runs the current project to the cursor’s location in the file and
stop program execution.
Reset Resets the device.
Set PC at cursor Sets the program counter (PC) value to the line address of the
cursor.
Focus Cursor at PC Moves the cursor to the current PC address.
Stack>Make Callee Current Makes the method being called the current call. Only available
when a call is selected in the Call Stack window.
Stack>Make Caller Current Makes the calling method the current call. Only available
when a call is selected in the Call Stack window.
Stack>Pop Topmost Call Pops the call on top of the stack.
Toggle Line Breakpoint Adds a line breakpoint or removes the breakpoint at the cursor
location in the program.
New Breakpoint Sets a new breakpoint at the specified line, exception, or
method.
New Watch Adds the specified symbol to watch.
New Run Time Watch Adds the specified symbol to watch that will change value as
the program runs/executes.
Disconnect from Debug Tool Disconnects communications between MPLAB® X IDE and
the debug tool. To reconnect, select Run/Debug Run.
Run Debugger/Programmer Performs a debug tool self-test. For tools that support a self
Self Test test, follow the tool documentation to set up the hardware and
then run this test to confirm proper operation.

 2011-2012 Microchip Technology Inc. DS52027B-page 161

MPLAB® X IDE User’s Guide

10.2.9 Team Menu

Below are the menu items in the Team menu.
For keyboard shortcuts of some of these menu items, see the table of contents for the
NetBeans help topic IDE Basics>Keyboard Shortcuts>Menu Shortcuts.

TABLE 10-9: TEAM MENU OPTIONS

Command Action
CVS, Mercurial, Subversion Displays submenus specific to each version management sys-
tem. Please see the product documentation for more on the
submenu options.
Local History Show local history of a file or revert file to history version.
Find Issues Find an issue in a version control system.
Report an Issue Report an issue to a version control system.
Create Build Job Create a build using a version control system.

10.2.10 Tools Menu

Below are the menu items in the Tools menu.
For keyboard shortcuts of some of these menu items, see the table of contents for the
NetBeans help topic IDE Basics>Keyboard Shortcuts>Menu Shortcuts.

TABLE 10-10: TOOLS MENU OPTIONS

Command Action
Embedded Visible if a plug-in has been added.
Licenses Allows roam in and out of compiler licenses.
Apply Diff Patch Select the Diff patch file and apply to your code.
Diff Compares two files selected in the IDE.
Add to Favorites Adds selected file to Favorites window.
Templates Opens the Templates Manager.
DTDs and XML Schemas Opens the DTDs and XML Schemas Manager.
Plugins Opens the Plugins Manager. For details, see NetBeans help,
“IDE Basics>Plugins>About Managing Plugins”.
Options Opens the Options dialog.
Mac OSX: Use mplab_ide>Preferences.

10.2.11 Window Menu

Below are the menu items in the Window menu.
For keyboard shortcuts of some of these menu items, see the table of contents for the
NetBeans help topic IDE Basics>Keyboard Shortcuts>Menu Shortcuts.

TABLE 10-11: WINDOW MENU OPTIONS

Command Action
Projects Opens the Projects window.
Files Opens the Files window.
Classes Opens the Classes window.
Favorites Opens the Favorites window.
Services Opens the Services window.
Tasks Opens the Task List window.
Dashboard Open the Dashboard window. See Section 5.15 “View the
Dashboard Display”.

DS52027B-page 162  2011-2012 Microchip Technology Inc.

 Desktop Reference
TABLE 10-11: WINDOW MENU OPTIONS (CONTINUED)
Command Action
Output>Output Opens or moves to front the Output window.
Output>Search Results Opens or moves to front the Search window.
Output>Find Usages Results Shows results of “Find Usages” in window.
Output>Versioning Output Shows results of version control action in window.
Output>Refactoring Preview Opens a Preview window of refactoring results.
Output>Disassembly Listing Opens the disassembly listing for the project Project.
File (Project Project)
Output>Call Graph Opens the Call Graph window.
Navigating>Navigator Opens the Navigator window.
Navigating>Hierarchy Opens a Hierarchy window.
Debugging>Variables Opens the Local Variables debugger window.
Debugging>Watches Opens the Watches debugger window.
Debugging>Call Stack Opens the Call Stack debugger window.
Debugging>Breakpoints Opens the Breakpoints window.
Debugging>Sessions Opens the Sessions window.
Debugging>Sources Opens the Sources window.
Debugging>Disassembly Opens the Disassembly window.
Debugging>PIC AppIO Opens the Application In/Out window. See MPLAB REAL ICE
in-circuit emulator documentation for more on Application I/O.
Debugging>Trace Opens the Trace window. See MPLAB REAL ICE in-circuit
emulator documentation for more on trace.
Debugging>Stopwatch Opens the Stopwatch window.
Debugging>PC Sampling Opens the PC Sampling window. See MPLAB REAL ICE
in-circuit emulator documentation for more on PC sampling
and profiling.
Versioning>CVS Select CVS version control items. For more on CVS, see
http://www.nongnu.org/cvs.
Versioning>Subversion Select Subversion version control items. For more on
Subversion, see http://subversion.tigris.org.
Versioning>Mercurial Select Mercurial version control items. For more on Mercurial,
see http://mercurial.selenic.com.
PIC Memory Views>Memory Opens specified Memory window. Memories shown depend
on the project device.
Simulator>Stimulus Opens the Simulator Stimulus window.
Simulator>Analyzer Opens the Simulator Analyzer window.
Other>Exception Reporter Opens the Exception Reporter window for exception break-
points.
Other>CSS Preview Opens the Preview window for a cascading style sheet.
Other>CSS Style Builder Opens the Style Builder window for cascading style sheet
rules.
Other>Macro Expansion Opens the Macro Expansion window to see macro structure.
Editor Opens an empty Editor window.
Close Window Closes the current tab in the current window. If the window
has no tabs, the whole window is closed.
Maximize Window Maximizes the Source Editor or the present window.
Undock Window Detaches the window from the IDE.
Clone Document Clones the active document.
Close All Documents Closes all open documents in the Source Editor.

 2011-2012 Microchip Technology Inc. DS52027B-page 163

MPLAB® X IDE User’s Guide
TABLE 10-11: WINDOW MENU OPTIONS (CONTINUED)
Command Action
Close Other Documents Closes all open documents except the active one.
Documents Opens the Documents dialog box, in which you can save and
close groups of open documents.
Reset Windows Resets windows to their default settings.

10.2.12 Help Menu

Below are the menu items in the Help menu.
For keyboard shortcuts of some of these menu items, see the table of contents for the
NetBeans help topic IDE Basics>Keyboard Shortcuts>Menu Shortcuts.

TABLE 10-12: HELP MENU OPTIONS

Command Action
Help Contents Displays the JavaHelp viewer with all installed help sets.
Online Docs and Support Opens the NetBeans support web page.
Keyboard Shortcuts Card Displays the keyboard shortcuts document.
Start Page Opens or moves the Start Page tab in front of any other open
tabs.
About Displays a window about MPLAB IDE.

DS52027B-page 164  2011-2012 Microchip Technology Inc.

 Desktop Reference

10.3 TOOLBARS
MPLAB IDE displays different toolbars depending on which features or tools you are
using. The icons in these toolbars provide shortcuts to routine tasks. To add or remove
icons from a toolbar, or create a new toolbar, see Section 6.5 “Customize Toolbars”.
Toolbar buttons may be grayed-out for various reasons. See
“Section 10.5 “Grayed-out or Missing Items and Buttons”.

Toolbars Available
The following basic toolbars are available.
• File Toolbar
• Clipboard Toolbar
• Status Flags Toolbar
• Undo/Redo Toolbar
• Run Toolbar
• Debug Toolbar
• Memory Toolbar
• Quick Search Toolbar
• Editor Toolbar

Toolbar Features
Toolbars have the following features:
• Hover the mouse pointer over an icon to pop up the icon function.
• Click and drag the toolbar to another location in the toolbar area.
• Right click in the toolbar area to show/hide a toolbar or change the contents of
some toolbars.
• Select View>Toolbars to show/hide a toolbar, change the contents of some
toolbars or create a custom toolbar.

10.3.1 File Toolbar

The File Toolbar currently contains button icons for the following functions. These
functions are also on the File menu.
• New File – Creates a new file with the New File wizard.
• New Project – Creates a new project with the New Project wizard.
• Open Project – Opens an existing project.
• Save All Files – Saves all open files.

10.3.2 Clipboard Toolbar

The Clipboard Toolbar currently contains button icons for the following functions. These
functions are also on the Edit menu.
• Cut – Deletes the current selection and places it on the clipboard.
• Copy – Copies the current selection to the clipboard.
• Paste – Pastes the contents of the clipboard into the insertion point.

10.3.3 Status Flags Toolbar

The Status Flags Toolbar contains:
• PC – Program Counter (PC) current value.

 2011-2012 Microchip Technology Inc. DS52027B-page 165

MPLAB® X IDE User’s Guide

10.3.4 Undo/Redo Toolbar

The Undo/Redo Toolbar currently contains button icons for the following functions.
These functions are also on the Edit menu.
• Undo – Reverses (one at a time) a series of editor actions, except Save.
• Redo – Reverses (one at a time) a series of Undo commands.

10.3.5 Run Toolbar

The Run Toolbar currently contains button icons for the following functions. These
functions are also on the Run, Debug and project context menus.
• Set Project Configuration – Selects project configuration. Choose “default” or
“Customize”.
• Build Project – Builds all the project files. Click on down arrow for other related
options.
• Clean and Build Project – Deletes files from previous builds and then builds the all
project files. Click on down arrow for other related options.
• Make and Program Device Project – Builds, programs the target and Runs the
selected project. Click on down arrow for other related options.
• Hold in Reset – Builds, programs the target and holds in Reset the selected
project.
• Read Device Memory – Reads target device memory and loads into MPLAB X
IDE. Click on down arrow for other related options.
• Debug Project – Builds, programs the target and Debug Runs the selected
project.

10.3.6 Debug Toolbar

The Debug Toolbar currently contains button icons for the following functions. These
functions are also on the Debug menu.
• Finish Debugger Session – Ends the debugging session.
• Pause – Pauses debugging. Use “Continue” to resume.
• Reset – Runs the current project to the cursor’s location in the file and stop
program execution.
• Continue – Resumes debugging until the next breakpoint or the end of the
program is reached.
• Step Over – Executes one source line of a program. If the line is a function call,
executes the entire function then stops.
• Step Over Expression – Steps over the expression and then stops the debugging.
• Step Into – Executes one source line of a program. If the line is a function call,
executes the program up to the function’s first statement and stops.
• Step Out – Executes one source line of a program. If the line is a function call,
executes the functions and returns control to the caller.
• Run to Cursor – Runs the current project to the cursor’s location in the file and
stop program execution.
• Apply Code Changes – Apply any changes in the code to the executing program.
• Set PC at cursor – Sets the program counter (PC) value to the line address of the
cursor.
• Focus Cursor at PC – Moves the cursor to the current PC address.

10.3.7 Memory Toolbar

The Memory Toolbar displays the current PC memory usage for MPLAB IDE. Click on
the display to force garbage collection.

DS52027B-page 166  2011-2012 Microchip Technology Inc.

 Desktop Reference

10.3.8 Quick Search Toolbar

The Quick Search Toolbar displays a search text box. Click the down arrow next to the
magnifying glass to select the type of search.

10.3.9 Editor Toolbar

The Editor Toolbar currently contains button icons for the following functions. These
functions are also on the Edit and Source menus. This toolbar appears at the top of the
tab containing the current file source code.
• Last Edited – Moves to the line that contains the last edit made.
• Back – Navigates back.
• Forward – Navigates forward.
• Find Selection – Finds the first occurrence of the selected text.
• Find Previous Occurrence – Finds the previous occurrence of the selected text.
• Find Next Occurrence – Finds the next occurrence of the selected text.
• Toggle Highlight Search – Turns on/off text selected for search.
• Previous Bookmark – Cycles backwards through the bookmarks.
• Next Bookmark – Cycles forward through the bookmarks.
• Toggle Bookmark – Sets a bookmark on a line of code.
• Shift Left – Moves the selected line or lines one tab to the left.
• Shift Right – Moves the selected line or lines one tab to the right.
• Start Macro Recording – Start recording keystrokes.
• Stop Macro Recording – Stop recording keystrokes.
• Comment – Makes selected line into a comment by adding “//”.
• Uncomment – Makes selected comment into a line by removing “//”.
• Go to Header/Source – Moves between the header and related source code.

10.4 STATUS BAR

The status bar will provide up-to-date information on the status of your MPLAB IDE
session. Currently only editor information is provided.

10.5 GRAYED-OUT OR MISSING ITEMS AND BUTTONS

There are several reasons why a menu item, toolbar button or status bar item may be
grayed-out (unavailable) or missing:
• The item/button is related to a device feature that the selected device does not
have, e.g., the PIC16F877A does not support external memory.
• The item/button is related to a tool feature that the selected tool does not have,
e.g., “Step Out” is not available on MPLAB ICD 3.
• The item/button is project-related and no project has been selected, e.g., project
build will not be available (No Active Project).
• The item/button is not supported for the selected device or tool.
• The item/button is performing its function and so cannot be selected again, e.g.,
“Run Project” is grayed-out when the program is running.
• The item/button is mutually exclusive to another item, e.g., “Pause” is available
when the program is running while “Continue” is grayed-out, and “Continue” is
available when the program is halted while “Pause” is grayed-out.

 2011-2012 Microchip Technology Inc. DS52027B-page 167

MPLAB® X IDE User’s Guide
NOTES:

DS52027B-page 168  2011-2012 Microchip Technology Inc.

 MPLAB® X IDE
USER’S GUIDE
Chapter 11. MPLAB X IDE Windows and Dialogs
11.1 INTRODUCTION
The MPLAB X IDE desktop is divided into panes containing tabbed windows. Not all of
these are visible until a feature has been selected.
As an example, when you first open MPLAB X IDE, only the Start Page is open. After
you open a project, the basic windows open – namely Project and Files in the top left
pane, Navigator in the bottom left pane, and Output in the bottom right pane. The Start
Page window moves into the top right pane.
MPLAB IDE windows are a combination of basic NetBeans windows and MPLAB IDE
specific windows. Dialogs open when selected from menu items. As with windows,
MPLAB IDE dialogs are a combination of basic NetBeans dialogs and MPLAB IDE spe-
cific dialogs. For information on NetBeans windows and dialogs, see Chapter
12. “NetBeans Windows and Dialogs”.
• MPLAB X IDE Windows with Related Menus and Dialogs
• MPLAB X IDE Wizards

11.2 MPLAB X IDE WINDOWS WITH RELATED MENUS AND DIALOGS

MPLAB X IDE uses some NetBeans windows as-is. However, other windows and their
related menus are modified or created specifically for embedded use.
Specific Windows* Related Menu
Customize Toolbars Window View>Toolbars
Dashboard Window Window
Memory Windows Window>PIC Memory Views
Output Window Window>Output>Output
Project Properties Window File
Projects Window Window
Tools Options Window Tools>Options (Windows, Linux OS)
mplab_ide>Preferences (Mac OSX)
Trace Window Window>Debugging
Watches Window Window>Debugging
* Depending on the tools you have installed, tool-specific windows may be available for
viewing. See the documentation for that tool for information about that window.

 2011-2012 Microchip Technology Inc. DS52027B-page 169

MPLAB® X IDE User’s Guide

11.2.1 Customize Toolbars Window

You can customize MPLAB X IDE toolbars using the Customize Toolbars window.
Select View>Toolbars>Customize to open the window.
For customization instructions, see Section 6.5 “Customize Toolbars”.

11.2.2 Dashboard Window

The Dashboard window contains general project information, such as checksums,
memory usage, and breakpoint resources. See Section 5.15 “View the Dashboard
Display” for details.

11.2.3 File Properties Window

Keep or exclude individual files from the build by using the File Properties window. See
Section 4.13 “Set File Properties” for details.

11.2.4 Memory Windows

Memory windows, called PIC Memory Views, display the many types of device mem-
ory, such as SFRs and Configuration bits. Use the “Memory” and “Format” drop-down
boxes to customize your window.
For more on these controls, see Section 4.22 “View/Change Device Memory
(including Configuration Bits)”.

FIGURE 11-1: MEMORY WINDOW CONTENT

DS52027B-page 170  2011-2012 Microchip Technology Inc.

 MPLAB X IDE Windows and Dialogs
11.2.4.1 MEMORY WINDOW MENU
Right clicking in the Memory window will display various options as shown below. Not
all options are available for all windows.

TABLE 11-1: MEMORY WINDOW MENU ITEM

Item Description
Virtual Address Display the type of address checked under the Address
Physical Address column.
Hex Display Width Set the hexadecimal display width. Options depend on the
device selected.
32-bit example:
One byte, e.g., 00 01 02 ... 0E 0F
Two bytes, e.g., 00 02 04 ... 0C 0E
Four bytes, e.g., 00 04 08 0C
Run to Cursor Run the program to the current cursor location.
Set PC at Cursor Set the Program Counter (PC) to the cursor location.
Focus Cursor on PC Center the current PC location in the window.
Toggle Breakpoint Toggle (on/off) existing breakpoint.
Symbolic Mode Display disassembled hex code with symbols.
Verbose Labels Show internal compiler labels.
Fill Memory Fill memory from Start Address to End Address with the value
in Data. Specify other options in the Fill Memory dialog.
Go To Go to the address/function specified in the Go To dialog.
Find Find text specified in the Find dialog.
Enable Multiline Rows Alter spacing of rows in the Configuration Bits window.
Output To File Write the displayed window contents to a text file. Specify a
range of data to output in the Output to File Range dialog.
Import Table Import tabular data from a file into a Memory window. Specify
a range of data to import in the Import Table Range dialog.
Export Table Export tabular data from a Memory window into a file. Specify
a range of data to export in the Export Table Range dialog.
Also, specify if the export is to be in a single column.
Print Print the contents of this window.
Adjust Table Columns Select which columns are visible.

Right clicking on the Window tab will display other options, such as Close,
Maximize/Minimize window, and Dock/Undock window.

 2011-2012 Microchip Technology Inc. DS52027B-page 171

MPLAB® X IDE User’s Guide

11.2.5 Output Window

The Task pane contains many windows, some inherited from NetBeans and some that
are specific to MPLAB X IDE. The Output window contains the MPLAB X IDE output
information. It is shown on tabs within the window.

TABLE 11-2: OUTPUT WINDOW TAB ITEMS

Item Description
Debugger Console Shows main debug actions, such as “User program running”.
Tool-specific Shows tool firmware version, device ID, and action status.
Build, Load Shows information and status on the build, and program loading.
Clean, Build, Load Shows information and status on the clean, build, and program
loading.
Peripheral Output Shows technical output from peripherals such as the UART with
the Simulator as the debug tool.

Right clicking in the Output window will display various options as shown below.

TABLE 11-3: OUTPUT WINDOW MENU ITEMS

Menu Item Description
Copy Copy selected text from the Output window to the clipboard.
Paste Paste selected text from the clipboard to the Output window.
Find Find the selected text, or enter other text to find, in the Output window.
You may use regular expressions and match case.
Find Next Find the next occurrence of the Find text.
Find Previous Find the previous occurrence of the Find text.
Filter Filter the output by text or regular expression.
Wrap Text Wrapped the text in the Output window.
Larger Font Make the font larger.
Smaller Font Make the font smaller.
Choose Font Select the font type, style and size.
Save As Save the selected text to a file.
Clear Clear all text in the Output window tab.
Close Close the Output window.

11.2.6 Project Properties Window

This window is used to view or change the project device, tools and tool settings. For
more information, see:
• Section 4.5 “View or Make Changes to Project Properties”
• Section 4.6 “Set Options for Debugger, Programmer or Language Tools”
• Section 5.5 “Loadable Projects and Files”
• Section 4.12 “Add and Set Up Library and Object Files”
• Section 4.14 “Set Build Properties”

DS52027B-page 172  2011-2012 Microchip Technology Inc.

 MPLAB X IDE Windows and Dialogs

11.2.7 Projects Window

The Projects window is a NetBeans window. However, it has been customized to show
the relevant virtual folders for an MPLAB X IDE project. Also, the context (right click)
menus have been customized with some MPLAB X IDE specific items.
• Projects Window – Logical Folders
• Projects Window – Project Menu
• Projects Window – File Menu

11.2.7.1 PROJECTS WINDOW – LOGICAL FOLDERS

Additional logical folders have been added to apply to MPLAB X projects. Therefore,
all folders displayed are:
• Header Files – MPLAB X IDE does not use this category when building. Consider
it a means to document a project’s dependency on a header file, and a convenient
method to access these files. You can double click on a file in the Project window
to open the file in an editor.
• Linker Files – You do not need to add a linker script to your project. The project
language tools will find the appropriate generic linker script for your device. Only if
you need to create your own linker script, should there be a file here.
There should be only one file in this folder. If you have more than one linker script,
only the first one has any effect – it is the linker script that the tool will use in the
link step.
• Source Files – These are the only files that the toolchain will accept as input to its
file commands.
• Important Files – Any file that does not fit into any of the other categories will end
up in this folder.
You can add simulator files – SBS, STC, SCL – and double click on them to open
the SCL Generator, Stimulus Controller, or editor, respectively.
You can add project-specific data sheets (PDFs) to this location in the Project win-
dow. Then, you can double click on the PDF to launch the data sheet. (This
requires that a PDF reader is installed.)
• Libraries – The toolchain should take all of the files in this folder, as well as the
object files, and include them in the final link step. For more information see
Section 4.12 “Add and Set Up Library and Object Files”.
• Loadables – Projects and files to combine with or replace your project hex files.
For more information see Section 5.5 “Loadable Projects and Files”.

 2011-2012 Microchip Technology Inc. DS52027B-page 173

MPLAB® X IDE User’s Guide
11.2.7.2 PROJECTS WINDOW – PROJECT MENU
Right click on a project name in the Projects window to pop up the Project menu
(Figure 11-2). MPLAB X IDE specific menu items are shown in Table 11-4.

FIGURE 11-2: PROJECT CONTEXT MENU

TABLE 11-4: PROJECT CONTEXT MENU ITEMS

Menu Item Description
New Add a new item. For MPLAB® X IDE, embedded file types are
available.
Locate Headers Locates all the header files (.h) called out in the project files and
presents them in checklist window so they may be added to the
project.
Although header files don't need to be added to your project in
order for that project to build, there are several reasons why you
might want to add them to the Project window under “Header
Files”:
• The files can be opened from the Project window for editing
instead of hunting for them on your computer.
• The “Save Project As” feature works better
• The “Package Project as .zip” feature works better
The project must be a C code project.
This feature is able to locate user-defined as well as standard
header files for the Microchip C18 and C30 toolsuites, but only
user-defined header files for the Microchip PIC32 C Compiler
toolsuite.
Export Hex Export the project build as a Hex file.
In MPLAB IDE v8, export is an extraction of memory objects. In
MPLAB X IDE, export is the hex file result of a build; therefore, it
needs to include all necessary auxiliary memory settings for
configuration and EEPROM in code.
Package Package the current project into a .zip file. While MPLAB X IDE
has the ability to zip files up, it cannot unzip them. So a sepa-
rate program will be required to unzip the project.
To package the project, this feature examines the project file to
determine the location of the project files to include. Only files
contained in the project folder and those using relative, not
absolute, paths will be included.
Items included in the package are the source files, makefile,
and nbproject directory.

DS52027B-page 174  2011-2012 Microchip Technology Inc.

 MPLAB X IDE Windows and Dialogs
TABLE 11-4: PROJECT CONTEXT MENU ITEMS (CONTINUED)
Menu Item Description
Set Configuration Opens the Project Properties dialog so you can set the project
configuration.
Make and Program Device Program the target device and hold in Reset (do not run).
Read Device Memory Read from the target device.
Properties Set project properties. For MPLAB X IDE, the Project Properties
window is specific to embedded development. See
Section 11.2.6 “Project Properties Window”.

11.2.7.3 PROJECTS WINDOW – FILE MENU

Right click on a file name in the Projects window to pop up the File menu. Table 11-5
shows MPLAB X IDE specific menu items.

TABLE 11-5: FILE CONTEXT MENU ITEMS

Menu Item Description
Properties Set file properties differently from the project properties. Select to exclude the file
from the build or override the project build options by selecting a different
configuration.

11.2.8 Tools Options Window

The Options window is a NetBeans window. However, it has been customized for
MPLAB X IDE projects through the addition of an Embedded button. After clicking on
this button, the following tabs and options will be available.
Open this window using Tools>Options (mplab_ide>Preferences for Mac OSX).
• Build Tools tab
• Project Options tab
• Generic Settings tab
• Suppressible Messages
• Other tab

11.2.8.1 BUILD TOOLS TAB

The information on this tab is accessed differently for Mac computers. Access the build
tools from mplab_ide>/preferences from the main menu bar. See Section 3.3.5 “Set
Language Tool Locations”.
Ensure that you have INSTALLED THE LANGUAGE TOOL or it will not show up on
“Tool Collection” list. If you know you have installed it but it is not on the list, click Scan
for compilers. If it is still not found click Add to add the tool to the list.
The following language tools are included with MPLAB X IDE:
• MPASM toolsuite – includes MPASM assembler, MPLINK linker and utilities.
• ASM30 toolsuite – includes the 16-bit assembler, linker and utilities.
• C32 toolsuite (free version) – includes the 32-bit compiler, assembler, linker and
utilities.
Other tools may be obtained from the Microchip web site (www.microchip.com) or third
parties.

 2011-2012 Microchip Technology Inc. DS52027B-page 175

MPLAB® X IDE User’s Guide
TABLE 11-6: BUILD TOOLS TAB ITEMS
Item Description
Tool Collection Shows a list of language tools installed on your computer. Select
the tool for your project and ensure that the paths (that apply) to
the right are correct.
Base directory: Path to the tool’s main folder
C compiler: Path to the C compiler (if available)
Assembler: Path to the assembler (if available)
Make command: Name of the make command generated by
MPLAB® X IDE.
Add Add a new language tool item to the list. Also consider using Scan
for Build Tools.
Remove Remove a language tool item from the list. This does not remove
the language tool from the computer.
Default Click on a tool and then click Default to make this tool the default
compiler/assembler for the selected device.
Scan for Build Tools Scan the computer for installed compilers/assemblers in various
default locations, not the whole system. If you install in a different
location, add the compiler manually.

11.2.8.2 PROJECT OPTIONS TAB

Set options related to the project.
TABLE 11-7: PROJECT OPTIONS TAB ITEMS
Item Description
Make Options Enter make options to use when building projects. These options
are toolchain dependent. See your language tool documentation.
File Path Mode Specify how to store file path information in a project.
Auto: Paths to files inside project folder stored as relative; paths to
files outside project folder stored as absolute.
Always Relative: All paths stored as relative to project folder.
Always Absolute: All paths stored as absolute (full path).
Save All Modified Files If selected, saves all unsaved files in the IDE before running make.
Before Running Make It is recommended to leave this property selected because modifi-
cations to files in the IDE are not recognized by make unless they
are first saved to disk.
Show binary files in If selected, the Projects view shows all files in a directory tree,
Project view including binary objects. This option is most relevant to projects
created with existing sources, which might place sources and bina-
ries in the same location. Deselect this option to more easily see
your C source files and header files.
Show profiler indicators If selected, profiler tools such as CPU Usage and Memory Usage
during run (new projects are set up to run by default when newly created projects are run.
only) The tools that are shown are determined by the Profile Configura-
tion selected in Tools>Profiler Tools.
Use parallel make If selected, make will execute several processes at a time, where
(make -j 2n) -j (or --jobs) is the option to run in parallel and 2n is the number
of processes, where n is the number of processors available on
your computer. If you have a single processor, parallel make will be
disabled.
If you wish, you can specify more processes by using “Make
Options”. Example: -j 10.
Note: MPASMX cannot run parallel make, either as a toolchain or
part of an MPLAB C18 project.

DS52027B-page 176  2011-2012 Microchip Technology Inc.

 MPLAB X IDE Windows and Dialogs
11.2.8.3 GENERIC SETTINGS TAB
Set up the log file and other project features.
TABLE 11-8: GENERIC SETTINGS TAB ITEMS

Item Description
Logging Level Set the message logging level.
OFF: No logging
SEVERE: Log severe (error) messages only.
WARNING: Log warning messages only.
INFO: Log informational messages only.
CONFIG: Log configuration information only.
FINE: Log some module to module communication.
FINER: Log more module to module communication.
FINEST: Log all module to module communication.
Log File Path and location of log file.
Projects Folder Path and location of the folder where you will place your MPLAB® X
IDE projects.
Close open source file Close any open source files in the Editor window when you close
on project close your project.
Clear output window Clear out the contents of the Output window when you build your
before build project.
Remove breakpoints When importing a file into your project, remove all existing project
upon importing a file breakpoints.
Halt build on first failure When building, halt the process on the first failure.
The selected project language tool can be set up to determine
which errors are produced. Go to the Project Properties dialog,
select the language tool under “Categories” and “Errors and
Warnings” under “Option Category”.
Maintain active connec- If selected, keep hardware tool connected always, not just at
tion to hardware tool runtime. (MPLAB® IDE v8 behavior)
Clear tool output window Clear out the contents of the Output window when you begin a Run,
on new session (debug, Debug Run or upload.
program, upload)
Silent build Build without generating messages in the Output window.
Enable alternate watch Display three watch view diamonds in the Watches window. Associ-
list views during debug ate a watch view with a watch variable. When you click on a watch
session view diamond, only the variables associated with that view will be
displayed. So this feature works like a filter.
Reset @ Select action on reset.
Main: Stop at main on reset.
Reset Vector: Stop at the Reset vector on Reset.
Debug start-up Select action on debug start.
Run: Start execution immediately.
Main: Stop at main.
Reset Vector: Stop at the Reset vector.

11.2.8.4 SUPPRESSIBLE MESSAGES

Select error and warming messages to suppress. Double click on available folders to
drill down to available items to suppress.

 2011-2012 Microchip Technology Inc. DS52027B-page 177

MPLAB® X IDE User’s Guide
11.2.8.5 OTHER TAB
Edit the lists of accepted file extensions for C/C++ and assembler source files and
header files. Also, set the default extension for each type.

Note: MPLAB X IDE does not support Fortran programming.

11.2.9 Trace Window

Tracing allows you to record the step-by-step execution of your code and examine this
recording. Trace is currently available for the following tools:
• Simulator
• MPLAB REAL ICE in-circuit emulator
Right clicking on a trace column in the window will pop up the context menu
(Table 11-9). Depending on the tool you are using, you may or may not see all menu
items.
Dialogs associated with trace are defined in Table 11-10.
TABLE 11-9: TRACE WINDOW CONTEXT MENU
Menu Item Description
Symbolic Mode For the “Instruction” column, toggle between displaying literal register
addresses (e.g., 0x5) or symbolic register macros (e.g., PORTA).
Go To Trigger: Move to the trigger line (0).
Top: Move to the top trace line.
Bottom: Move to the bottom trace line.
Trace Line: Specify and go to a trace line location. Opens a Go To dialog.
Go To Source Select a trace line and then select this option to go to the corresponding line
Line in source code.
Display Time For the “Cycle” column (will display if not previously visible):
As Hex Cycle Count: Display cycle count as hexadecimal
As Decimal Cycle Count: Display cycle count as decimal
In Seconds Elapsed: Display cycle count in seconds elapsed
In Engineering Format: Display cycle count in the appropriate engineering
format (powers of 103).
Clear Trace File Clear the data in the trace display.
Find Find items in trace display. Opens a Find dialog.
Output To File Save the trace data to a file. Opens Define Range dialog, which opens a
Save dialog.
Print Print the data. Opens a Print dialog.
Adjust Table Auto-adjust the columns in the trace display to fit the data.
Columns
Reload View Reload the original data view for the trace display at pause.

TABLE 11-10: TRACE DIALOGS

Dialog Description
Go To Specify a trace line to go to.
Find Find a line number or other data in the trace display.
Output to File Range Specify a range of lines to output to a file. Click OK to proceed to the
Save dialog to save the data to a text file.
Save Save data to a text file.
Print Specify the printer, page setup and appearance before printing.

DS52027B-page 178  2011-2012 Microchip Technology Inc.

 MPLAB X IDE Windows and Dialogs

11.2.10 Watches Window

Use the Watches window to watch the values of symbols that you select change. To
open the Watches window, select Window>Debugging>Watches.

Right click on a row to open the Watches menu. The items available will depend on
whether a symbol is in the row or what debug tool you are using.
TABLE 11-11: WATCHES WINDOW MENU ITEMS
Menu Item Description
New Watch Add a new symbol to watch
New Runtime Watch MPLAB REAL ICE In-Circuit Emulator Only
Add a new runtime watch for the selected symbol.
Run Time Update Interval MPLAB REAL ICE In-Circuit Emulator Only
Specify the rate at which the symbol value will be updated. “No
Delay” will update as quickly as your personal computer is able. If
you are seeing errors in the runtime data, you can add a delay to
decrease the update speed.
Export All Watches to List Export information about the symbols to be watched to a file
File (.xwatch).
Delete All Remove all the watched symbols from the Watches window.

Note: You can also right-click in a symbol in code to add it to a New Watch or New
Runtime Watch.

You can change the columns displayed in the window by right clicking on a heading to
pop up the “Change Visible Columns” dialog.
TABLE 11-12: CHANGE VISIBLE COLUMNS ITEMS
Dialog Item If Checked
Name Show name of column (always checked)
Address Show memory address of variable
Binary Show binary formatted value
Char Show character formatted value
Decimal Show decimal formatted value
Type Show type of watch variable
Value Show value of watch expression (in hexadecimal)

For more on the Watches window, see the NetBeans Help topic C/C++/Fortran
Development>Debugging C/C++/Fortran Applications with gdb>Viewing C/C++/For-
tran Program Information>Creating a C/C++/Fortran Watch.

11.3 MPLAB X IDE WIZARDS

MPLAB X IDE uses many NetBeans windows. However, some windows have been
modified or created specifically for embedded use.
• New Project wizard – see Section 4.3 “Create a New Project”
• New File wizard – see Section 4.9 “Create a New File”
• Import Image File wizard – see Section 5.4.3 “Import Image File Wizard”

 2011-2012 Microchip Technology Inc. DS52027B-page 179

MPLAB® X IDE User’s Guide
NOTES:

DS52027B-page 180  2011-2012 Microchip Technology Inc.

 MPLAB® X IDE
USER’S GUIDE
Chapter 12. NetBeans Windows and Dialogs
12.1 INTRODUCTION
MPLAB IDE windows are a combination of basic NetBeans windows and MPLAB IDE
specific windows. Dialogs open when selected from menu items. As with windows,
MPLAB IDE dialogs are a combination of basic NetBeans dialogs and MPLAB IDE spe-
cific dialogs.
NetBeans windows and dialogs are discussed here, with references to documentation
in the Help. For information on MPLAB X IDE specific windows and dialogs, see
Chapter 11. “MPLAB X IDE Windows and Dialogs”.
• NetBeans Specific Windows and Window Menus
• NetBeans Specific Dialogs

12.2 NETBEANS SPECIFIC WINDOWS AND WINDOW MENUS

NetBeans windows are discussed in NetBeans help. To open help on a window, click
on the Window tab to select it and then hit the <F1> key. If no help can be found, select
Help>Help Contents and click on the help file’s Search tab to search for information on
that window. Or see the table of contents for the NetBeans help topic “Managing IDE
Windows”.
To open most windows, see the Section 10.2.11 “Window Menu”.
Windows may be docked and undocked (right click on Window tab) and have
window-specific pop-up, or context, menus with items such as Fill, Goto, and Edit Cells.
Right clicking in a window or on an item in the window will pop up a context menu. Most
content menu items are also located on menus on the desktop menu bar (see
Section 10.2 “Menus”).
Set up window properties by selecting Tools>Options (mplab_ide>Preferences for Mac
OSX), Miscellaneous Button, Appearance tab.

12.3 NETBEANS SPECIFIC DIALOGS

NetBeans dialogs are discussed in NetBeans help. To open help on a dialog, click on
the Help button on the dialog or, if there is no Help button, hit the <F1> key. If no help
can be found, select Help>Help Contents and click on the help file’s Search tab to
search for information on that dialog.
To open most dialogs, see Section 10.2 “Menus”.

 2011 Microchip Technology Inc. DS52027A-page 181

MPLAB® X IDE User’s Guide
NOTES:

DS52027A-page 182  2011 Microchip Technology Inc.

 MPLAB® X IDE
USER’S GUIDE
Chapter 13. Project Files and Folders
13.1 INTRODUCTION
There are two ways to view project files and folders in MPLAB X IDE:
• Projects Window View
• Files Window View
Other MPLAB X IDE file and folder information includes:
• Importing an MPLAB IDE v8 Project – Relative Paths
• Moving a Project
• Building a Project Outside of MPLAB X IDE

13.2 PROJECTS WINDOW VIEW

Project folders viewed in the Projects window are logical (virtual) folders. For more on
this window, see the table of contents for the NetBeans help topic “Projects Window”.
At the least, you will need to add source files. MPLAB X IDE will find many default files
for you (header files, linker scripts). You may add library and precompiled object files,
as well as edited header and linker script files. Files that will not be included in the build
may be placed under “Important Files”.

FIGURE 13-1: PROJECTS WINDOW – SIMPLE C CODE PROJECT

TABLE 13-1: PROJECTS WINDOW DEFINITIONS

Virtual Folder Files Contained
Header Files Header files (.h or .inc)
Library Files Library files (.a or .lib)
Linker Files Linker files (.ld, .gld or .lkr)
Object Files Precompiled object files (.o)
Source Files Source files (.c or .asm)
Important Files Important files, such as makefiles. Other documents can be placed
here, such as data sheet PDFs.

 2011-2012 Microchip Technology Inc. DS52027B-page 183

MPLAB® X IDE User’s Guide

13.3 FILES WINDOW VIEW

Project folders viewed in the Files window are actual folders (folders on your personal
computer). For more on this window, see the table of contents for the NetBeans help
topic “Files Window” as used with C code projects.

FIGURE 13-2: FILES WINDOW - SIMPLE C CODE PROJECT

DS52027B-page 184  2011-2012 Microchip Technology Inc.

 Project Files and Folders
TABLE 13-2: FILES WINDOW DEFINITIONS
Folder Description
MyProject The project folder, which contains the Makefile file and C code or
assembly application files.
Makefile is the master makefile for the project. This file is generated at
project creation time and it is not touched after that (it will not be regener-
ated). You can make changes to this file if you are familiar with GNU make.
But MPLAB X IDE provides ways to add a pre-step and post-step (Project
Properties) which can be used instead of modifying the Makefile itself.
build(1) The intermediate files folder. Files are contained in subfolders depending on
project configuration, usage and location.
The build files are:
• Run files (.o)
• Dependency files (.o.d)
• HI-TECH® intermediate files (.p1)
dist(1) The output files folder. Files are contained in subfolders depending on
project configuration, usage and location.
The distribution files are:
• Executable files (.hex)
• ELF or COFF object files (.elf or .cof)
• library files (.a or .lib)
nbproject The makefile and metadata folder. Contains these files:
• Project makefile
• Configuration-specific makefiles
• project.xml IDE-generated metadata file
• configurations.xml metadata file
default, The project configurations folders. If no configurations are created by the
MyConfig(2) developer, all code is in default.
production, The production and debug versions folders.
debug(2)
_ext(2) The external project files folder. If a file is referenced outside the project
folder, it is listed here.
Note 1: You do not need to check these folders into source control. A build will create them.
See also Section 5.17 “Control Source Code”.
Note 2: These items are not shown in Figure 13-2.

 2011-2012 Microchip Technology Inc. DS52027B-page 185

MPLAB® X IDE User’s Guide

13.4 IMPORTING AN MPLAB IDE V8 PROJECT – RELATIVE PATHS

For an MPLAB IDE v8 project located at:
C:\MyProjects\mplab8project
On importing to MPLAB X IDE you will get:
C:\MyProjects\mplab8project\mplab8project.X
The MPLAB X IDE imported project is placed by default under the MPLAB IDE v8
project to preserve maintainability of both projects. However, you can place the MPLAB
X IDE project folder anywhere. Also, the name of the project will be set as
mplab8project.X but you can rename it if you wish. There is a convention to finish
the name of an MPLAB X IDE project with .X but this is just a convention.
The new project will not copy the source files into its folder, but instead will reference
the location of the files in the v8 folder. To create an independent MPLAB X IDE project,
create a new project and copy the MPLAB IDE v8 source files to it.
For details, see Section 5.3 “Import MPLAB Legacy Project”.

13.5 MOVING A PROJECT

If you want to move your project, see the table of contents for the NetBeans help topic
C/C++/Fortran Development>Working with C/C++/Fortran Projects>Moving, Copying,
or Renaming a C/C++/Fortran Project.
You can also use an external tool; the project file structure does not require you to use
MPLAB X IDE.

13.6 BUILDING A PROJECT OUTSIDE OF MPLAB X IDE

MPLAB X IDE uses the GNU make as its build tool. For Linux, you are expected to have
make installed. For Mac OSX and Windows, the installation of MPLAB X IDE provides
this program. The locations are:
• Windows 32-Bit OS - C:\Program Files\Microchip\MPLABX\
gnuBins\GnuWin32\bin
• Windows 64-Bit OS - C:\Program Files (x86)\Microchip\MPLABX\
gnuBins\GnuWin32\bin
• Mac OS X - /Applications/microchip/mplabx/mplab_ide.app/
Contents/Resources/mplab_ide/bin
MPLAB X IDE automatically adds the directory containing this make into the path. If you
want to build outside of the IDE you must add this directory to your path.
The Makefile in the MPLAB X IDE project directory can be called directly to build the
default configuration:
Command - Type on a single line Description
$ make clean To remove all intermediate objects and final images
$ make To create the production image (Hex file)
$ make TYPE_IMAGE=DEBUG_RUN To create the debug image (COF/ELF file)

DS52027B-page 186  2011-2012 Microchip Technology Inc.

 Project Files and Folders
If the project has more than one configuration, then:
Command - Type on a single line Description
$ make -f Makefile To remove all intermediate objects and final
CONF=Configuration clean images for configuration Configuration.
$ make -f Makefile To create the production image (Hex file) for
CONF=Configuration configuration Configuration.
$ make -f Makefile To create the debug image (COF/ELF file) for
CONF=Configuration configuration Configuration.
TYPE_IMAGE=DEBUG_RUN

The names of the images by default are (with respect to the MPLAB X IDE directory):
dist/$CONF_NAME/production/$PROJ_NAME.production.hex
dist/$CONF_NAME/debug/$PROJ_NAME.debug.cof (or elf)

 2011-2012 Microchip Technology Inc. DS52027B-page 187

MPLAB® X IDE User’s Guide
NOTES:

DS52027B-page 188  2011-2012 Microchip Technology Inc.

 MPLAB® X IDE
USER’S GUIDE
Chapter 14. Configuration Settings Summary
14.1 INTRODUCTION
Examples of how to set Configuration bits in code for different language tools and
related devices are shown below. For more information on how to set Configuration
bits, see your language tool documentation. For some language tools, a configurations
settings document is available listing all configuration settings for a device. Otherwise,
consult your device header file for macros.
• MPASM Toolchain
• HI-TECH® PICC™ Toolchain
• HI-TECH® PICC-18™ Toolchain
• C18 Toolchain
• ASM30 Toolchain
• C30 Toolchain
• C32 Toolchain
• XC Toolchains

14.2 MPASM TOOLCHAIN

Two types of assembler directives are used to set device configuration bits: __config
and config. DO NOT mix __config and config in the same code.

14.2.1 __config
The directive __config is used for PIC10/12/16 MCUs. It may be used for PIC18
MCUs (excluding PIC18FXXJ devices) but the config directive is recommended. The
syntax is as follows:
__config expr ;For a single configuration word
or
__config addr, expr ;For multiple configuration word
where:
addr: Address of the Configuration Word. May be literal but usually represented by a
macro.
Note: Macros must be listed in ascending register order.
expr: Expression representing the value to which the specified Configuration bits will be
set. May be literal but usually represented by a macro or macros ANDed together.

Macros are specified in the device include file (*.inc) that is located in the Windows
OS default directory:
C:\Program Files\Microchip\MPLABX\mpasmx
Directive case does not matter; __CONFIG or __config is acceptable. Macro case
should match what is in the header.

 2011-2012 Microchip Technology Inc. DS52027B-page 189

MPLAB® X IDE User’s Guide
Example – PIC10/12/16 MCUs
#include p16f877a.inc

;Set oscillator to HS, watchdog time off, low-voltage prog. off

__CONFIG _HS_OSC & _WDT_OFF & _LVP_OFF
Example – PIC18 MCUs
#include p18f452.inc

;Oscillator switch enabled, RC oscillator with OSC2 as I/O pin.

__CONFIG _CONFIG1, _OSCS_OFF_1 & _RCIO_OSC_1

;Watch Dog Timer enable, Watch Dog Timer PostScaler count - 1:128
__CONFIG _CONFIG3, _WDT_ON_3 & _WDTPS_128_3

14.2.2 config
The directive config is used for PIC18 MCUs (including PIC18FXXJ devices). The
syntax is as follows:
config setting=value [, setting=value]
where:
setting: Macro representing a Configuration bit or bits.
value: Macro representing the value to which the specified Configuration bit(s) will be
set. Multiple settings may be defined on a single line, separated by commas.
Settings for a single configuration byte may also be defined on separate lines.
Macros are specified in the device include file (*.inc) that is located in the Windows
OS default directory:
C:\Program Files\Microchip\MPLABX\mpasmx
Directive case does not matter; __CONFIG or __config is acceptable. Macro case
should match what is in the header.
Example – PIC18 MCUs
#include p18f452.inc

;Oscillator switch enabled, RC oscillator with OSC2 as I/O pin.

CONFIG OSCS=ON, OSC=LP

;Watch Dog Timer enable, Watch Dog Timer PostScaler count - 1:128
CONFIG WDT=ON, WDTPS=128

DS52027B-page 190  2011-2012 Microchip Technology Inc.

 Configuration Settings Summary

14.3 HI-TECH® PICC™ TOOLCHAIN

A macro specified in the htc.h header file is used to set device Configuration Words
for PIC10/12/16 MCUs:
__CONFIG(x);
where
x: Expression representing the value to which the specified Configuration bits will be
set. May be literal but usually represented by a macro or macros ANDed together.
Macros are specified in the device header file (*.h) that is located in the Windows OS
default directory:
C:\Program Files\HI-TECH Software\PICC\version\include
where version is the version number of the compiler.
For devices that have more than one Configuration Word location, each subsequent
invocation of __CONFIG() will modify the next Configuration Word in sequence.
Macro case should match what is in the relevant header. For htc.c, __CONFIG() is
correct but __config() is not.

PICC Example
#include <htc.h>

__CONFIG(WDTDIS & XT & UNPROTECT); // Program config. word 1

__CONFIG(FCMEN); // Program config. word 2

14.4 HI-TECH® PICC-18™ TOOLCHAIN

A macro specified in the htc.h header file is used to set device Configuration Words
for PIC18 MCUs:
__CONFIG(n,x);
where
n: Configuration register number
x: Expression representing the value to which the specified Configuration bits will be
set. May be literal but usually represented by a macro or macros ANDed together.
Macros are specified in the device header file (*.h) that is located in the Windows OS
default directory:
C:\Program Files\HI-TECH Software\PICC\version\include
where version is the version number of the compiler.
Macro case should match what is in the relevant header. For htc.c, __CONFIG() is
correct but __config() is not.

PICC-18 Example
#include <htc.h>

//Oscillator switch enabled, RC oscillator with OSC2 as I/O pin.

__CONFIG(1, LP);

//Watch Dog Timer enable, Watch Dog Timer PostScaler count - 1:128
__CONFIG(2, WDTEN & WDTPS128);

 2011-2012 Microchip Technology Inc. DS52027B-page 191

MPLAB® X IDE User’s Guide

14.5 C18 TOOLCHAIN

The #pragma config directive specifies the device-specific configuration settings
(i.e., Configuration bits) to be used by the application:
#pragma config setting-list
where
setting-list: A list of one or more setting-name = value-name macro pairs,
separated by commas.
Macros are specified in the device header file (*.h) that is located in the Windows OS
default directory:
C:\program files\microchip\mplabc18\version\.h
Pragma case does not matter; either #PRAGMA CONFIG or #pragma config is
acceptable. Macro case should match what is in the header.
Example
#include <p18cxxx.h>

/*Oscillator switch enabled, RC oscillator with OSC2 as I/O pin.*/

#pragma config OSCS = ON, OSC = LP

/*Watch Dog Timer enable, Watch Dog Timer PostScaler count - 1:128*/
#pragma config WDT = ON, WDTPS = 128

14.6 ASM30 TOOLCHAIN

A macro specified in the device include file is used to set Configuration bits:
config __reg, value
where
__reg: Configuration register name macro.
value: Expression representing the value to which the specified Configuration bits will be
set. May be literal but usually represented by a macro or macros ANDed together.
Macros are specified in the device include file (*.inc) that is located in the Windows
OS default directory:
C:\Program Files\Microchip\MPLAB ASM30 Suite\Support\device\inc
where device is the abbreviation of the selected 16-bit device, i.e., PIC24F, PIC24H,
dsPIC30F, or dsPIC33F.
Macro case should match what is in the relevant header. For example, config is
correct but CONFIG is not.
Example
.include "p30fxxxx.inc"

;Clock switching off, Fail-safe clock monitoring off,

; Use External Clock
config __FOSC, CSW_FSCM_OFF & XT_PLL16

;Turn off Watchdog Timer

config __FWDT, WDT_OFF

DS52027B-page 192  2011-2012 Microchip Technology Inc.

 Configuration Settings Summary

14.7 C30 TOOLCHAIN

Two types of compiler macros are used to set device Configuration bits: one type for
PIC24F MCUs and one type for dsPIC30F and dsPIC33F/PIC24H devices.

14.7.1 PIC24F Configuration Settings

Macros are provided in device header files to set Configuration bits:
_confign(value);
where
n: Configuration register number.
value: Expression representing the value to which the specified Configuration bits will be
set. May be literal but usually represented by a macro or macros ANDed together.
Macros are specified in the device header file (*.h) that is located in the Windows OS
default directory:
C:\Program Files\Microchip\MPLAB C30\support\PIC24F\h
Macro case should match what is in the relevant header. For example, _CONFIG1 is
correct but _config1 is not.
Example – PIC24F MCUs
#include “p24Fxxxx.h”

//JTAG off, Code Protect off, Write Protect off, COE mode off, WDT off
_CONFIG1( JTAGEN_OFF & GCP_OFF & GWRP_OFF & COE_OFF & FWDTEN_OFF )

//Clock switching/monitor off, Oscillator (RC15) on,

// Oscillator in HS mode, Use primary oscillator (no PLL)
_CONFIG2( FCKSM_CSDCMD & OSCIOFNC_ON & POSCMOD_HS & FNOSC_PRI )

14.7.2 dsPIC30F/33F/PIC24H Configuration Settings

Macros are provided in device header files to set Configuration bits:
_reg(value);
where
_reg: Configuration register name macro.
value: Expression representing the value to which the specified Configuration bits will be
set. May be literal but usually represented by a macro or macros ANDed together.
Macros are specified in the device header file (*.h) that is located in the Windows OS
default directory:
C:\Program Files\Microchip\MPLAB C30\support\device\h
where device is the abbreviation of the selected 16-bit device, i.e., PIC24H,
dsPIC30F, or dsPIC33F.
Macro case should match what is in the relevant header. For example, _FOSC is correct
but _fosc is not.

 2011-2012 Microchip Technology Inc. DS52027B-page 193

MPLAB® X IDE User’s Guide
Example – dsPIC30F DSCs
#include “p30fxxxx.h”

//Clock switching and failsafe clock monitoring off,

// Oscillator in HS mode
_FOSC(CSW_FSCM_OFF & HS);

//Watchdog timer off

_FWDT(WDT_OFF);

//Brown-out off, Master clear on

_FBORPOR(PBOR_OFF & MCLR_EN);
Example – dsPIC33F/PIC24H Devices
#include “p33fxxxx.h”

// Use primary oscillator (no PLL)

_FOSCSEL(FNOSC_PRI);

//Oscillator in HS mode
_FOSC(POSCMD_HS);

//Watchdog timer off

_FWDT(FWDTEN_OFF);

//JTAG off
_FICD(JTAGEN_OFF);

DS52027B-page 194  2011-2012 Microchip Technology Inc.

 Configuration Settings Summary

14.8 C32 TOOLCHAIN

The #pragma config directive specifies the device-specific configuration settings
(i.e., Configuration bits) to be used by the application:
# pragma config setting-list
where
setting-list: A list of one or more setting-name = value-name macro pairs,
separated by commas.
Macros are specified in the device header file (*.h) that is located in the Windows OS
default directory:
C:\Program Files\Microchip\MPLAB C32\pic32mx\include\proc
Pragma case does not matter; either #PRAGMA CONFIG or #pragma config is
acceptable. Macro case should match what is in the header.

Example
#include “p32xxxx.h”

//Enables the Watchdog Timer,

// Sets the Watchdog Postscaler to 1:128
#pragma config FWDTEN = ON, WDTPS = PS128

//Selects the HS Oscillator for the Primary Oscillator

#pragma config POSCMOD = HS

14.9 XC TOOLCHAINS
To create code that is as portable as possible, refer to the Common Compiler Interface
(CCI) chapter, config macro, in each of the following documents:
• MPLAB XC8 C Compiler (DS52053) or related help file
• MPLAB XC16 C Compiler (DS52071) or related help file
• MPLAB XC32 C Compiler (DS51686) or related help file

 2011-2012 Microchip Technology Inc. DS52027B-page 195

MPLAB® X IDE User’s Guide
NOTES:

DS52027B-page 196  2011-2012 Microchip Technology Inc.

 MPLAB® X IDE
USER’S GUIDE
Appendix A. Revision History
Revision A (November 2011)
• Initial release of this document.
Revision B (December 2012)
• JRE installation now automatic with Windows and Linux. Mac instructions
provided. Discussed in Chapter 2. “Before You Begin”, 2.1 “Install JRE and
MPLAB X IDE”.
• Corrected information on device driver names and paths in Chapter 2.
• Added description of meaning of the two lights next to a debug tool in Chapter 3.
“Tutorial” and Chapter 4. “Basic Tasks”.
• Updated Icon definitions in Chapter 3. “Tutorial” and Chapter 4. “Basic Tasks”.
• Added a list of language toolchain abbreviations in Chapter 4. “Basic Tasks”, 4.2
“Create a New Project”, 4.2.5 “Step 5: Select Compiler”.
• Multiple dialogs updated to show projects using the new MPLAB XC C compiler.
• Added information on the Libraries category in the Project Properties dialog in
Chapter 4. “Basic Tasks”, 4.11 “Add and Setup Library and Object Files”.
• Added information on normalizing a hex file under Chapter 4. “Basic Tasks”, 4.13
“Set Build Properties”.
• Added information on how to add a literal value to a Watches window in Chapter
4. “Basic Tasks”, 4.19 “Watch Symbol Values Changes”.
• Updated several sections for recent support of C++ (currently for the MPLAB
XC32++ Compiler).
• Added section on loadable projects in Chapter 5. “Additional Tasks”, 5.4
“Loadable Projects and Files”.
• Discussed how to import embedded projects from other applications into MPLAB
X IDE in Chapter 5. “Additional Tasks”, 5.6 “Other Embedded Projects”.
• Added information on working with samples projects in Chapter 5. “Additional
Tasks”, 5.5 “Sample Projects”.
• Described how to work with other files, like XML, in Chapter 5. “Additional Tasks”,
5.6 “Work with Other Types of Files”.
• Added information on how to work with log files in Chapter 6. Advanced Tasks”,
6.3 “Log Data”.
• Described how to add functions to a toolbar in Chapter 6. Advanced Tasks”, 6.4
“Customize Toolbars”.
• Added Chapter 7 Editor, that discusses MPLAB X IDE Editor usage, options and
features.
• Described an error message you might receive if you modify or move the default
linker script, and how to avoid this. See Chapter 8. “Troubleshooting”, 8.3 “MPLAB
X IDE Issues”.
• Combined “Major Differences” and “Feature Differences” into Chapter 9. “MPLAB
X IDE vs. MPLAB IDE v8”, 9.1 “Major Differences”. Explained NetBeans platform
is open source, but MPLAB X IDE is proprietary.

 2011-2012 Microchip Technology Inc. DS52027B-page 197

MPLAB® X IDE User’s Guide
• In Chapter 9. “MPLAB X IDE vs. MPLAB IDE v8”, updated 9.2 “Menu Differences”
to reflect new functions in MPLAB X IDE and 9.3 “Tool Support Differences” to
reflect new plug-in support.
• In Chapter 10. “Desktop Reference”, updated 10.1 “Menus” to reflect new
functions in MPLAB X IDE.
• Split “Windows and Dialogs” into Chapter 11. “MPLAB X IDE Windows and
Dialogs” and Chapter 12. “NetBeans Windows and Dialogs” to better delineate the
different windows. Updated window menus.
• Updated project file structure in Chapter 13. “Project Files and Folders”, 13.2
“Files Window View”. Added information on makefiles.
• Updated discussion of MPLAB XC C compiler configuration bits to reference the
common c interface (CCI) in Chapter 14. “Configuration Settings Summary”, 14.8
“XC Toolchains”.

DS52027B-page 198  2011-2012 Microchip Technology Inc.

 MPLAB® X IDE
USER’S GUIDE
Support
INTRODUCTION
Please refer to the items discussed here for support issues.
• Warranty Registration
• myMicrochip Personalized Notification Service
• The Microchip Web Site
• Microchip Forums
• Customer Support
• Contact Microchip Technology

WARRANTY REGISTRATION
Web Site: http://www.microchipdirect.com
Registering your development tool entitles you to receive new product updates. Interim
software releases are available at the Microchip web site.

myMICROCHIP PERSONALIZED NOTIFICATION SERVICE

myMicrochip: http://www.microchip.com/pcn
Microchip’s personal notification service helps keep customers current on their
Microchip products of interest. Subscribers will receive e-mail notification whenever
there are changes, updates, revisions or errata related to a specified product family or
development tool.
Please visit myMicrochip to begin the registration process and select your preferences
to receive personalized notifications. A FAQ and registration details are available on
the page, which can be opened by selecting the link above.
When you are selecting your preferences, choosing “Development Systems” will pop-
ulate the list with available development tools. The main categories of tools are listed
below:
• Compilers – The latest information on Microchip C compilers, assemblers, linkers
and other language tools. These include all MPLAB C compilers; all MPLAB
assemblers (including MPASM™ assembler); all MPLAB linkers (including
MPLINK™ object linker); and all MPLAB librarians (including MPLIB™ object
librarian).
• Emulators – The latest information on Microchip in-circuit emulators. This
includes the MPLAB REAL ICE™ in-circuit emulator.
• In-Circuit Debuggers – The latest information on Microchip in-circuit debuggers.
These include the PICkit™ 2, PICkit 3 and MPLAB ICD 3 in-circuit debuggers.
• MPLAB® IDE – The latest information on Microchip MPLAB IDE, the Windows®
Integrated Development Environment for development systems tools. This list is
focused on the MPLAB IDE, MPLAB IDE Project Manager, MPLAB Editor and
MPLAB SIM simulator, as well as general editing and debugging features.

 2011-2012 Microchip Technology Inc. DS52027B-page 199

MPLAB® X IDE User’s Guide
• Programmers – The latest information on Microchip programmers. These include
the device (production) programmers MPLAB REAL ICE in-circuit emulator,
MPLAB ICD 3 in-circuit debugger, MPLAB PM3 and development (nonproduction)
programmers PICkit 2 and 3.
• Starter/Demo Boards – These include MPLAB Starter Kit boards, PICDEM demo
boards, and various other evaluation boards.

THE MICROCHIP WEB SITE

Web Site: http://www.microchip.com
Microchip provides online support via our web site. This web site is used as a means
to make files and information easily available to customers. Accessible by using your
favorite Internet browser, the web site contains the following information:
• Product Support – Data sheets and errata, application notes and sample
programs, design resources, user’s guides and hardware support documents,
latest software releases and archived software
• General Technical Support – Frequently Asked Questions (FAQs), technical
support requests, online discussion groups, Microchip consultant program
member listing
• Business of Microchip – Product selector and ordering guides, latest Microchip
press releases, listing of seminars and events, listings of Microchip sales offices,
distributors and factory representatives

MICROCHIP FORUMS
Forums: http://www.microchip.com/forums
Microchip provides additional online support via our web forums. Currently available
forums are:
• Development Tools
• 8-bit PIC MCUs
• 16-bit PIC MCUs
• 32-bit PIC MCUs

CUSTOMER SUPPORT
Users of Microchip products can receive assistance through several channels:
• Distributor or Representative
• Local Sales Office
• Field Application Engineer (FAE)
• Technical Support
Customers should contact their distributor, representative or field application engineer
(FAE) for support. Local sales offices are also available to help customers. A listing of
sales offices and locations is included in the back of this document. See our web site
for a complete, up-to-date listing of sales offices.
Technical Support: http://support.microchip.com
Documentation errors or comments may be e-mailed to [email protected].

DS52027B-page 200  2011-2012 Microchip Technology Inc.

 Support

CONTACT MICROCHIP TECHNOLOGY

Call or fax Microchip Technology Corporate offices at the numbers below:
Voice: (480) 792-7200
Fax: (480) 792-7277

 2011-2012 Microchip Technology Inc. DS52027B-page 201

MPLAB® X IDE User’s Guide
NOTES:

DS52027B-page 202  2011-2012 Microchip Technology Inc.

 MPLAB® X IDE
USER’S GUIDE
Glossary
A
Absolute Section
A section with a fixed (absolute) address that cannot be changed by the linker.
Access Memory
PIC18 Only – Special registers on PIC18 devices that allow access regardless of the
setting of the Bank Select Register (BSR).
Access Entry Points
Access entry points provide a way to transfer control across segments to a function
which may not be defined at link time. They support the separate linking of boot and
secure application segments.
Address
Value that identifies a location in memory.
Alphabetic Character
Alphabetic characters are those characters that are letters of the arabic alphabet
(a, b, …, z, A, B, …, Z).
Alphanumeric
Alphanumeric characters are comprised of alphabetic characters and decimal digits
(0,1, …, 9).
ANDed Breakpoints
Set up an ANDed condition for breaking, i.e., breakpoint 1 AND breakpoint 2 must
occur at the same time before a program halt. This can only be accomplished if a data
breakpoint and a program memory breakpoint occur at the same time.
Anonymous Structure
16-bit C Compiler – An unnamed structure.
PIC18 C Compiler – An unnamed structure that is a member of a C union. The mem-
bers of an anonymous structure may be accessed as if they were members of the
enclosing union. For example, in the following code, hi and lo are members of an
anonymous structure inside the union caster.
union castaway
int intval;
struct {
char lo; //accessible as caster.lo
char hi; //accessible as caster.hi
};
} caster;
ANSI
American National Standards Institute is an organization responsible for formulating
and approving standards in the United States.
Application
A set of software and hardware that may be controlled by a PIC® microcontroller.

 2011-2012 Microchip Technology Inc. DS52027B-page 203

MPLAB® X IDE User’s Guide
Archive/Archiver
An archive/library is a collection of relocatable object modules. It is created by assem-
bling multiple source files to object files, and then using the archiver/librarian to com-
bine the object files into one archive/library file. An archive/library can be linked with
object modules and other archives/libraries to create executable code.
ASCII
American Standard Code for Information Interchange is a character set encoding that
uses 7 binary digits to represent each character. It includes upper and lowercase
letters, digits, symbols and control characters.
Assembly/Assembler
Assembly is a programming language that describes binary machine code in a sym-
bolic form. An assembler is a language tool that translates assembly language source
code into machine code.
Assigned Section
A section which has been assigned to a target memory block in the linker command file.
Asynchronously
Multiple events that do not occur at the same time. This is generally used to refer to
interrupts that may occur at any time during processor execution.
Attribute
Characteristics of variables or functions in a C program which are used to describe
machine-specific properties.
Attribute, Section
Characteristics of sections, such as “executable”, “read-only”, or “data” that can be
specified as flags in the assembler .section directive.
B
Binary
The base two numbering system that uses the digits 0-1. The rightmost digit counts
ones, the next counts multiples of 2, then 22 = 4, etc.
Breakpoint
Hardware Breakpoint: An event whose execution will cause a Halt.
Software Breakpoint: An address where execution of the firmware will halt. Usually
achieved by a special break instruction.
Build
Compile and link all the source files for an application.
C
C\C++
C is a general purpose programming language which features economy of expression,
modern control flow and data structures, and a rich set of operators. C++ is the
object-oriented version of C.
Calibration Memory
A Special Function Register or registers used to hold values for calibration of a PIC
microcontroller on-board RC oscillator or other device peripherals.

DS52027B-page 204  2011-2012 Microchip Technology Inc.

 Glossary
Central Processing Unit
The part of a device that is responsible for fetching the correct instruction for execution,
decoding that instruction, and then executing that instruction. When necessary, it works
in conjunction with the arithmetic logic unit (ALU) to complete the execution of the
instruction. It controls the program memory address bus, the data memory address
bus, and accesses to the stack.
Clean
Clean removes all intermediary project files, such as object, hex and debug files, for
the active project. These files are recreated from other files when a project is built.
COFF
Common Object File Format. An object file of this format contains machine code,
debugging and other information.
Command Line Interface
A means of communication between a program and its user based solely on textual
input and output.
Compiler
A program that translates a source file written in a high-level language into machine
code.
Conditional Assembly
Assembly language code that is included or omitted based on the assembly-time value
of a specified expression.
Conditional Compilation
The act of compiling a program fragment only if a certain constant expression, specified
by a preprocessor directive, is true.
Configuration Bits
Special purpose bits programmed to set PIC microcontroller modes of operation. A
Configuration bit may or may not be preprogrammed.
Control Directives
Directives in assembly language code that cause code to be included or omitted based
on the assembly-time value of a specified expression.
CPU
See Central Processing Unit.
Cross Reference File
A file that references a table of symbols and a list of files that references the symbol. If
the symbol is defined, the first file listed is the location of the definition. The remaining
files contain references to the symbol.
D
Data Directives
Data directives are those that control the assembler’s allocation of program or data
memory and provide a way to refer to data items symbolically; that is, by meaningful
names.
Data Memory
On Microchip MCU and DSC devices, data memory (RAM) is comprised of General
Purpose Registers (GPRs) and Special Function Registers (SFRs). Some devices also
have EEPROM data memory.

 2011-2012 Microchip Technology Inc. DS52027B-page 205

MPLAB® X IDE User’s Guide
Data Monitor and Control Interface (DMCI)
The Data Monitor and Control Interface, or DMCI, is a tool in MPLAB X IDE. The inter-
face provides dynamic input control of application variables in projects. Applica-
tion-generated data can be viewed graphically using any of 4 dynamically-assignable
graph windows.
Debug/Debugger
See ICE/ICD.
Debugging Information
Compiler and assembler options that, when selected, provide varying degrees of infor-
mation used to debug application code. See compiler or assembler documentation for
details on selecting debug options.
Deprecated Features
Features that are still supported for legacy reasons, but will eventually be phased out
and no longer used.
Device Programmer
A tool used to program electrically programmable semiconductor devices such as
microcontrollers.
Digital Signal Controller
A digital signal controller (DSC) is a microcontroller device with digital signal processing
capability, i.e., Microchip dsPIC DSC devices.
Digital Signal Processing\Digital Signal Processor
Digital signal processing (DSP) is the computer manipulation of digital signals, com-
monly analog signals (sound or image), which have been converted to digital form
(sampled). A digital signal processor is a microprocessor that is designed for use in
digital signal processing.
Directives
Statements in source code that provide control of the language tool’s operation.
Download
Download is the process of sending data from a host to another device, such as an
emulator, programmer or target board.
DWARF
Debug With Arbitrary Record Format. DWARF is a debug information format for ELF
files.
E
EEPROM
Electrically Erasable Programmable Read Only Memory. A special type of PROM that
can be erased electrically. Data is written or erased one byte at a time. EEPROM
retains its contents even when power is turned off.
ELF
Executable and Linking Format. An object file of this format contains machine code.
Debugging and other information is specified in with DWARF. ELF/DWARF provide
better debugging of optimized code than COFF.
Emulation/Emulator
See ICE/ICD.
Endianness
The ordering of bytes in a multi-byte object.

DS52027B-page 206  2011-2012 Microchip Technology Inc.

 Glossary
Environment
MPLAB PM3 – A folder containing files on how to program a device. This folder can be
transferred to a SD/MMC card.
Epilogue
A portion of compiler-generated code that is responsible for deallocating stack space,
restoring registers and performing any other machine-specific requirement specified in
the runtime model. This code executes after any user code for a given function,
immediately prior to the function return.
EPROM
Erasable Programmable Read Only Memory. A programmable read-only memory that
can be erased usually by exposure to ultraviolet radiation.
Error/Error File
An error reports a problem that makes it impossible to continue processing your pro-
gram. When possible, an error identifies the source file name and line number where
the problem is apparent. An error file contains error messages and diagnostics gener-
ated by a language tool.
Event
A description of a bus cycle which may include address, data, pass count, external
input, cycle type (fetch, R/W), and time stamp. Events are used to describe triggers,
breakpoints and interrupts.
Executable Code
Software that is ready to be loaded for execution.
Export
Send data out of the MPLAB IDE in a standardized format.
Expressions
Combinations of constants and/or symbols separated by arithmetic or logical
operators.
Extended Microcontroller Mode
In Extended Microcontroller mode, on-chip program memory as well as external mem-
ory is available. Execution automatically switches to external if the program memory
address is greater than the internal memory space of the PIC18 device.
Extended Mode (PIC18 MCUs)
In Extended mode, the compiler will utilize the extended instructions (i.e., ADDFSR,
ADDULNK, CALLW, MOVSF, MOVSS, PUSHL, SUBFSR and SUBULNK) and the indexed
with literal offset addressing.
External Label
A label that has external linkage.
External Linkage
A function or variable has external linkage if it can be referenced from outside the
module in which it is defined.
External Symbol
A symbol for an identifier which has external linkage. This may be a reference or a
definition.

 2011-2012 Microchip Technology Inc. DS52027B-page 207

MPLAB® X IDE User’s Guide
External Symbol Resolution
A process performed by the linker in which external symbol definitions from all input
modules are collected in an attempt to resolve all external symbol references. Any
external symbol references which do not have a corresponding definition cause a linker
error to be reported.
External Input Line
An external input signal logic probe line (TRIGIN) for setting an event based upon
external signals.
External RAM
Off-chip Read/Write memory.
F
Fatal Error
An error that will halt compilation immediately. No further messages will be produced.
File Registers
On-chip data memory, including General Purpose Registers (GPRs) and Special
Function Registers (SFRs).
Filter
Determine by selection what data is included/excluded in a trace display or data file.
Flash
A type of EEPROM where data is written or erased in blocks instead of bytes.
FNOP
Forced No Operation. A forced NOP cycle is the second cycle of a two-cycle instruction.
Since the PIC microcontroller architecture is pipelined, it prefetches the next instruction
in the physical address space while it is executing the current instruction. However, if
the current instruction changes the program counter, this prefetched instruction is
explicitly ignored, causing a forced NOP cycle.
Frame Pointer
A pointer that references the location on the stack that separates the stack-based
arguments from the stack-based local variables. Provides a convenient base from
which to access local variables and other values for the current function.
Free-Standing
An implementation that accepts any strictly conforming program that does not use
complex types and in which the use of the features specified in the library clause (ANSI
‘89 standard clause 7) is confined to the contents of the standard headers <float.h>,
<iso646.h>, <limits.h>, <stdarg.h>, <stdbool.h>, <stddef.h> and
<stdint.h>.
G
GPR
General Purpose Register. The portion of device data memory (RAM) available for
general use.

DS52027B-page 208  2011-2012 Microchip Technology Inc.

 Glossary

H
Halt
A stop of program execution. Executing Halt is the same as stopping at a breakpoint.
Heap
An area of memory used for dynamic memory allocation where blocks of memory are
allocated and freed in an arbitrary order determined at runtime.
Hex Code\Hex File
Hex code is executable instructions stored in a hexadecimal format code. Hex code is
contained in a hex file.
Hexadecimal
The base 16 numbering system that uses the digits 0-9 plus the letters A-F (or a-f). The
digits A-F represent hexadecimal digits with values of (decimal) 10 to 15. The rightmost
digit counts ones, the next counts multiples of 16, then 162 = 256, etc.
High Level Language
A language for writing programs that is further removed from the processor than
assembly.
I
ICE/ICD
In-Circuit Emulator/In-Circuit Debugger: A hardware tool that debugs and programs a
target device. An emulator has more features than an debugger, such as trace.
In-Circuit Emulation/In-Circuit Debug: The act of emulating or debugging with an in-cir-
cuit emulator or debugger.
-ICE/-ICD: A device (MCU or DSC) with on-board in-circuit emulation or debug circuitry.
This device is always mounted on a header board and used to debug with an in-circuit
emulator or debugger.
ICSP
In-Circuit Serial Programming. A method of programming Microchip embedded
devices using serial communication and a minimum number of device pins.
IDE
Integrated Development Environment, as in MPLAB IDE.
Identifier
A function or variable name.
IEEE
Institute of Electrical and Electronics Engineers.
Import
Bring data into the MPLAB IDE from an outside source, such as from a hex file.
Initialized Data
Data which is defined with an initial value. In C,
int myVar=5;
defines a variable which will reside in an initialized data section.
Instruction Set
The collection of machine language instructions that a particular processor
understands.

 2011-2012 Microchip Technology Inc. DS52027B-page 209

MPLAB® X IDE User’s Guide
Instructions
A sequence of bits that tells a central processing unit to perform a particular operation
and can contain data to be used in the operation.
Internal Linkage
A function or variable has internal linkage if it can not be accessed from outside the
module in which it is defined.
International Organization for Standardization
An organization that sets standards in many businesses and technologies, including
computing and communications. Also known as ISO.
Interrupt
A signal to the CPU that suspends the execution of a running application and transfers
control to an Interrupt Service Routine (ISR) so that the event may be processed. Upon
completion of the ISR, normal execution of the application resumes.
Interrupt Handler
A routine that processes special code when an interrupt occurs.
Interrupt Service Request (IRQ)
An event which causes the processor to temporarily suspend normal instruction exe-
cution and to start executing an interrupt handler routine. Some processors have
several interrupt request events allowing different priority interrupts.
Interrupt Service Routine (ISR)
Language tools – A function that handles an interrupt.
MPLAB IDE – User-generated code that is entered when an interrupt occurs. The loca-
tion of the code in program memory will usually depend on the type of interrupt that has
occurred.
Interrupt Vector
Address of an Interrupt Service Routine (ISR) or interrupt handler.
L
L-value
An expression that refers to an object that can be examined and/or modified. An l-value
expression is used on the left-hand side of an assignment.
Latency
The time between an event and its response.
Library/Librarian
See Archive/Archiver.
Linker
A language tool that combines object files and libraries to create executable code,
resolving references from one module to another.
Linker Script Files
Linker script files are the command files of a linker. They define linker options and
describe available memory on the target platform.
Listing Directives
Listing directives are those directives that control the assembler listing file format. They
allow the specification of titles, pagination and other listing control.

DS52027B-page 210  2011-2012 Microchip Technology Inc.

 Glossary
Listing File
A listing file is an ASCII text file that shows the machine code generated for each C
source statement, assembly instruction, assembler directive, or macro encountered in
a source file.
Little Endian
A data ordering scheme for multi-byte data whereby the Least Significant Byte (LSB)
is stored at the lower addresses.
Local Label
A local label is one that is defined inside a macro with the LOCAL directive. These
labels are particular to a given instance of a macro’s instantiation. In other words, the
symbols and labels that are declared as local are no longer accessible after the ENDM
macro is encountered.
Logic Probes
Up to 14 logic probes can be connected to some Microchip emulators. The logic probes
provide external trace inputs, trigger output signal, +5V, and a common ground.
Loop-Back Test Board
Used to test the functionality of the MPLAB REAL ICE in-circuit emulator.
LVDS
Low Voltage Differential Signaling. A low noise, low-power, low amplitude method for
high-speed (gigabits per second) data transmission over copper wire.
With standard I/0 signaling, data storage is contingent upon the actual voltage level.
Voltage level can be affected by wire length (longer wires increase resistance, which
lowers voltage). But with LVDS, data storage is distinguished only by positive and neg-
ative voltage values, not the voltage level. Therefore, data can travel over greater
lengths of wire while maintaining a clear and consistent data stream.
Source: http://www.webopedia.com/TERM/L/LVDS.html.
M
Machine Code
The representation of a computer program that is actually read and interpreted by the
processor. A program in binary machine code consists of a sequence of machine
instructions (possibly interspersed with data). The collection of all possible instructions
for a particular processor is known as its “instruction set”.
Machine Language
A set of instructions for a specific central processing unit, designed to be usable by a
processor without being translated.
Macro
Macro instruction. An instruction that represents a sequence of instructions in abbrevi-
ated form.
Macro Directives
Directives that control the execution and data allocation within macro body definitions.
Makefile
Export to a file the instructions to Make the project. Use this file to Make your project
outside of MPLAB IDE, i.e., with a make.
Make Project
A command that rebuilds an application, recompiling only those source files that have
changed since the last complete compilation.

 2011-2012 Microchip Technology Inc. DS52027B-page 211

MPLAB® X IDE User’s Guide
MCU
Microcontroller Unit. An abbreviation for microcontroller. Also uC.
Memory Model
For C compilers, a representation of the memory available to the application. For the
PIC18 C compiler, a description that specifies the size of pointers that point to program
memory.
Message
Text displayed to alert you to potential problems in language tool operation. A message
will not stop operation.
Microcontroller
A highly integrated chip that contains a CPU, RAM, program memory, I/O ports and
timers.
Microcontroller Mode
One of the possible program memory configurations of PIC18 microcontrollers. In
Microcontroller mode, only internal execution is allowed. Thus, only the on-chip pro-
gram memory is available in Microcontroller mode.
Microprocessor Mode
One of the possible program memory configurations of PIC18 microcontrollers. In
Microprocessor mode, the on-chip program memory is not used. The entire program
memory is mapped externally.
Mnemonics
Text instructions that can be translated directly into machine code. Also referred to as
opcodes.
MPASM™ Assembler
Microchip Technology’s relocatable macro assembler for PIC microcontroller devices,
KEELOQ® devices and Microchip memory devices.
MPLAB Language Tool for Device
Microchip’s C compilers, assemblers and linkers for specified devices. Select the type
of language tool based on the device you will be using for your application, e.g., if you
will be creating C code on a PIC18 MCU, select the MPLAB C Compiler for PIC18
MCUs.
MPLAB ICD
Microchip’s in-circuit debuggers that works with MPLAB IDE. See ICE/ICD.
MPLAB IDE
Microchip’s Integrated Development Environment. MPLAB IDE comes with an editor,
project manager and simulator.
MPLAB PM3
A device programmer from Microchip. Programs PIC18 microcontrollers and dsPIC
digital signal controllers. Can be used with MPLAB IDE or stand-alone. Replaces
PRO MATE II.
MPLAB REAL ICE™ In-Circuit Emulator
Microchip’s next-generation in-circuit emulators that works with MPLAB IDE. See
ICE/ICD.
MPLAB SIM
Microchip’s simulator that works with MPLAB IDE in support of PIC MCU and dsPIC
DSC devices.

DS52027B-page 212  2011-2012 Microchip Technology Inc.

 Glossary
MPLIB™ Object Librarian
Microchip's librarian that works with MPLAB X IDE or MPLAB IDE v8. MPLIB librarian
is an object librarian for use with ELF or COFF object modules created using either
MPASM assembler or MPLAB C Compiler for PIC18 MCUs.
MPLINK™ Object Linker
MPLINK linker is an object linker for the Microchip MPASM assembler and the Micro-
chip C18 C compiler. MPLINK linker also may be used with the Microchip MPLIB librar-
ian. MPLINK linker is designed to be used with MPLAB IDE, though it does not have to
be.
MRU
Most Recently Used. Refers to files and windows available to be selected from MPLAB
IDE main pull-down menus.
N
Native Data Size
For Native trace, the size of the variable used in a Watch window must be of the same
size as the selected device’s data memory: bytes for PIC18 devices and words for
16-bit devices.
Nesting Depth
The maximum level to which macros can include other macros.
Node
MPLAB IDE project component.
Non-Extended Mode (PIC18 MCUs)
In Non-Extended mode, the compiler will not utilize the extended instructions nor the
indexed with literal offset addressing.
Non Real Time
Refers to the processor at a breakpoint or executing single-step instructions or MPLAB
IDE being run in Simulator mode.
Nonvolatile Storage
A storage device whose contents are preserved when its power is off.
NOP
No Operation. An instruction that has no effect when executed except to advance the
program counter.
O
Object Code/Object File
Object code is the machine code generated by an assembler or compiler. An object file
is a file containing machine code and possibly debug information. It may be immedi-
ately executable or it may be relocatable, requiring linking with other object files, e.g.,
libraries, to produce a complete executable program.
Object File Directives
Directives that are used only when creating an object file.
Octal
The base 8 number system that only uses the digits 0-7. The rightmost digit counts
ones, the next digit counts multiples of 8, then 82 = 64, etc.

 2011-2012 Microchip Technology Inc. DS52027B-page 213

MPLAB® X IDE User’s Guide
Off-Chip Memory
Off-chip memory refers to the memory selection option for the PIC18 device where
memory may reside on the target board, or where all program memory may be supplied
by the emulator. The Memory tab accessed from Options>Development Mode
provides the Off-Chip Memory selection dialog box.
Opcodes
Operational Codes. See Mnemonics.
Operators
Symbols, like the plus sign ‘+’ and the minus sign ‘-’, that are used when forming
well-defined expressions. Each operator has an assigned precedence that is used to
determine order of evaluation.
OTP
One Time Programmable. EPROM devices that are not in windowed packages. Since
EPROM needs ultraviolet light to erase its memory, only windowed devices are eras-
able.
P
Pass Counter
A counter that decrements each time an event (such as the execution of an instruction
at a particular address) occurs. When the pass count value reaches zero, the event is
satisfied. You can assign the Pass Counter to break and trace logic, and to any
sequential event in the complex trigger dialog.
PC
Personal Computer or Program Counter.
PC Host
Any personal computer running a supported Windows operating system.
Persistent Data
Data that is never cleared or initialized. Its intended use is so that an application can
preserve data across a device Reset.
Phantom Byte
An unimplemented byte in the dsPIC architecture that is used when treating the 24-bit
instruction word as if it were a 32-bit instruction word. Phantom bytes appear in dsPIC
hex files.
PIC MCUs
PIC microcontrollers (MCUs) refers to all Microchip microcontroller families.
PICkit 2 and 3
Microchip’s developmental device programmers with debug capability through Debug
Express. See the Readme files for each tool to see which devices are supported.
Plug-ins
The MPLAB IDE has both built-in components and plug-in modules to configure the
system for a variety of software and hardware tools. Several plug-in tools may be found
under the Tools menu.
Pod
The enclosure for an in-circuit emulator or debugger. Other names are “Puck”, if the
enclosure is round, and “Probe”, not be confused with logic probes.

DS52027B-page 214  2011-2012 Microchip Technology Inc.

 Glossary
Power-on-Reset Emulation
A software randomization process that writes random values in data RAM areas to
simulate uninitialized values in RAM upon initial power application.
Pragma
A directive that has meaning to a specific compiler. Often a pragma is used to convey
implementation-defined information to the compiler. MPLAB C30 uses attributes to
convey this information.
Precedence
Rules that define the order of evaluation in expressions.
Production Programmer
A production programmer is a programming tool that has resources designed in to pro-
gram devices rapidly. It has the capability to program at various voltage levels and com-
pletely adheres to the programming specification. Programming a device as fast as
possible is of prime importance in a production environment where time is of the
essence as the application circuit moves through the assembly line.
Profile
For MPLAB SIM simulator, a summary listing of executed stimulus by register.
Program Counter
The location that contains the address of the instruction that is currently executing.
Program Counter Unit
16-bit assembler – A conceptual representation of the layout of program memory. The
program counter increments by 2 for each instruction word. In an executable section,
2 program counter units are equivalent to 3 bytes. In a read-only section, 2 program
counter units are equivalent to 2 bytes.
Program Memory
The memory area in a device where instructions are stored.
Project
A project contains the files needed to build an application (source code, linker script
files, etc.) along with their associations to various build tools and build options.
Prologue
A portion of compiler-generated code that is responsible for allocating stack space, pre-
serving registers and performing any other machine-specific requirement specified in
the runtime model. This code executes before any user code for a given function.
Prototype System
A term referring to a user’s target application, or target board.
PWM Signals
Pulse-Width Modulation Signals. Certain PIC MCU devices have a PWM peripheral.
Q
Qualifier
An address or an address range used by the Pass Counter or as an event before
another operation in a complex trigger.
R
Radix
The number base, hex, or decimal, used in specifying an address.

 2011-2012 Microchip Technology Inc. DS52027B-page 215

MPLAB® X IDE User’s Guide
RAM
Random Access Memory (Data Memory). Memory in which information can be
accessed in any order.
Raw Data
The binary representation of code or data associated with a section.
Read Only Memory
Memory hardware that allows fast access to permanently stored data but prevents
addition to or modification of the data.
Real Time
When an in-circuit emulator or debugger is released from the Halt state, the processor
runs in Real Time mode and behaves exactly as the normal chip would behave. In Real
Time mode, the real time trace buffer of an emulator is enabled and constantly captures
all selected cycles, and all break logic is enabled. In an in-circuit emulator or debugger,
the processor executes in real time until a valid breakpoint causes a Halt, or until the
user halts the execution.
In the simulator, real time simply means execution of the microcontroller instructions as
fast as they can be simulated by the host CPU.
Recursive Calls
A function that calls itself, either directly or indirectly.
Recursion
The concept that a function or macro, having been defined, can call itself. Great care
should be taken when writing recursive macros; it is easy to get caught in an infinite
loop where there will be no exit from the recursion.
Reentrant
A function that may have multiple, simultaneously active instances. This may happen
due to either direct or indirect recursion or through execution during interrupt
processing.
Relaxation
The process of converting an instruction to an identical, but smaller instruction. This is
useful for saving on code size. MPLAB ASM30 currently knows how to RELAX a CALL
instruction into an RCALL instruction. This is done when the symbol that is being called
is within +/- 32k instruction words from the current instruction.
Relocatable
An object whose address has not been assigned to a fixed location in memory.
Relocatable Section
16-bit assembler – A section whose address is not fixed (absolute). The linker assigns
addresses to relocatable sections through a process called relocation.
Relocation
A process performed by the linker in which absolute addresses are assigned to relo-
catable sections and all symbols in the relocatable sections are updated to their new
addresses.
ROM
Read Only Memory (Program Memory). Memory that cannot be modified.
Run
The command that releases the emulator from halt, allowing it to run the application
code and change or respond to I/O in real time.

DS52027B-page 216  2011-2012 Microchip Technology Inc.

 Glossary
Run-time Model
Describes the use of target architecture resources.
Runtime Watch
A Watch window where the variables change in as the application is run. See individual
tool documentation to determine how to set up a runtime watch. Not all tools support
runtime watches.
S
Scenario
For MPLAB SIM simulator, a particular setup for stimulus control.
Section
A portion of an application located at a specific address of memory.
Section Attribute
A characteristic ascribed to a section (e.g., an access section).
Sequenced Breakpoints
Breakpoints that occur in a sequence. Sequence execution of breakpoints is
bottom-up; the last breakpoint in the sequence occurs first.
Serialized Quick Turn Programming
Serialization allows you to program a serial number into each microcontroller device
that the Device Programmer programs. This number can be used as an entry code,
password or ID number.
Shell
The MPASM assembler shell is a prompted input interface to the macro assembler.
There are two MPASM assembler shells: one for the DOS version and one for the
Windows version.
Simulator
A software program that models the operation of devices.
Single Step
This command steps through code, one instruction at a time. After each instruction,
MPLAB IDE updates register windows, watch variables, and status displays so you can
analyze and debug instruction execution. You can also single-step C compiler source
code, but instead of executing single instructions, MPLAB IDE will execute all assembly
level instructions generated by the line of the high level C statement.
Skew
The information associated with the execution of an instruction appears on the proces-
sor bus at different times. For example, the executed opcodes appears on the bus as
a fetch during the execution of the previous instruction, the source data address and
value and the destination data address appear when the opcodes is actually executed,
and the destination data value appears when the next instruction is executed. The trace
buffer captures the information that is on the bus at one instance. Therefore, one trace
buffer entry will contain execution information for three instructions. The number of cap-
tured cycles from one piece of information to another for a single instruction execution
is referred to as the skew.
Skid
When a hardware breakpoint is used to halt the processor, one or more additional
instructions may be executed before the processor halts. The number of extra
instructions executed after the intended breakpoint is referred to as the skid.

 2011-2012 Microchip Technology Inc. DS52027B-page 217

MPLAB® X IDE User’s Guide
Source Code
The form in which a computer program is written by the programmer. Source code is
written in a formal programming language which can be translated into machine code
or executed by an interpreter.
Source File
An ASCII text file containing source code.
Special Function Registers (SFRs)
The portion of data memory (RAM) dedicated to registers that control I/O processor
functions, I/O status, timers or other modes or peripherals.
SQTP
See Serialized Quick Turn Programming.
Stack, Hardware
Locations in PIC microcontroller where the return address is stored when a function call
is made.
Stack, Software
Memory used by an application for storing return addresses, function parameters, and
local variables. This memory is typically managed by the compiler when developing
code in a high-level language.
MPLAB Starter Kit for Device
Microchip’s starter kits contains everything needed to begin exploring the specified
device. View a working application and then debug and program your own changes.
Static RAM or SRAM
Static Random Access Memory. Program memory you can read/write on the target
board that does not need refreshing frequently.
Status Bar
The Status Bar is located on the bottom of the MPLAB IDE window and indicates such
current information as cursor position, development mode and device, and active tool
bar.
Step Into
This command is the same as Single Step. Step Into (as opposed to Step Over) follows
a CALL instruction into a subroutine.
Step Over
Step Over allows you to debug code without stepping into subroutines. When stepping
over a CALL instruction, the next breakpoint will be set at the instruction after the CALL.
If for some reason the subroutine gets into an endless loop or does not return properly,
the next breakpoint will never be reached. The Step Over command is the same as
Single Step except for its handling of CALL instructions.
Step Out
Step Out allows you to step out of a subroutine which you are currently stepping
through. This command executes the rest of the code in the subroutine and then stops
execution at the return address to the subroutine.
Stimulus
Input to the simulator, i.e., data generated to exercise the response of simulation to
external signals. Often the data is put into the form of a list of actions in a text file.
Stimulus may be asynchronous, synchronous (pin), clocked and register.

DS52027B-page 218  2011-2012 Microchip Technology Inc.

 Glossary
Stopwatch
A counter for measuring execution cycles.
Storage Class
Determines the lifetime of the memory associated with the identified object.
Storage Qualifier
Indicates special properties of the objects being declared (e.g., const).
Symbol
A symbol is a general purpose mechanism for describing the various pieces which
comprise a program. These pieces include function names, variable names, section
names, file names, struct/enum/union tag names, etc. Symbols in MPLAB IDE refer
mainly to variable names, function names and assembly labels. The value of a symbol
after linking is its value in memory.
Symbol, Absolute
Represents an immediate value such as a definition through the assembly .equ
directive.
System Window Control
The system window control is located in the upper left corner of windows and some dia-
logs. Clicking on this control usually pops up a menu that has the items “Minimize,”
“Maximize,” and “Close.”
T
Target
Refers to user hardware.
Target Application
Software residing on the target board.
Target Board
The circuitry and programmable device that makes up the target application.
Target Processor
The microcontroller device on the target application board.
Template
Lines of text that you build for inserting into your files at a later time. The MPLAB Editor
stores templates in template files.
Tool Bar
A row or column of icons that you can click on to execute MPLAB IDE functions.
Trace
An emulator or simulator function that logs program execution. The emulator logs pro-
gram execution into its trace buffer which is uploaded to MPLAB IDE’s trace window.
Trace Memory
Trace memory contained within the emulator. Trace memory is sometimes called the
trace buffer.
Trace Macro
A macro that will provide trace information from emulator data. Since this is a software
trace, the macro must be added to code, the code must be recompiled or reassembled,
and the target device must be programmed with this code before trace will work.

 2011-2012 Microchip Technology Inc. DS52027B-page 219

MPLAB® X IDE User’s Guide
Trigger Output
Trigger output refers to an emulator output signal that can be generated at any address
or address range, and is independent of the trace and breakpoint settings. Any number
of trigger output points can be set.
Trigraphs
Three-character sequences, all starting with ??, that are defined by ISO C as
replacements for single characters.
U
Unassigned Section
A section which has not been assigned to a specific target memory block in the linker
command file. The linker must find a target memory block in which to allocate an
unassigned section.
Uninitialized Data
Data which is defined without an initial value. In C,
int myVar;
defines a variable which will reside in an uninitialized data section.
Upload
The Upload function transfers data from a tool, such as an emulator or programmer, to
the host personal computer or from the target board to the emulator.
USB
Universal Serial Bus. An external peripheral interface standard for communication
between a computer and external peripherals over a cable using bi-serial transmission.
V
Vector
The memory locations that an application will jump to when either a Reset or interrupt
occurs.
W
Warning
MPLAB IDE – An alert that is provided to warn you of a situation that would cause phys-
ical damage to a device, software file, or equipment.
16-bit assembler/compiler – Warnings report conditions that may indicate a problem,
but do not halt processing. In MPLAB C30, warning messages report the source file
name and line number, but include the text ‘warning:’ to distinguish them from error
messages.
Watch Variable
A variable that you may monitor during a debugging session in a Watch window.
Watch Window
Watch windows contain a list of watch variables that are updated at each breakpoint.
Watchdog Timer (WDT)
A timer on a PIC microcontroller that resets the processor after a selectable length of
time. The WDT is enabled or disabled and set up using Configuration bits.
Workbook
For MPLAB SIM stimulator, a setup for generation of SCL stimulus.

DS52027B-page 220  2011-2012 Microchip Technology Inc.

 MPLAB® X IDE
USER’S GUIDE
Index
Symbols Cannot find file - Linker Error ................................. 142
__DEBUG .......................................................122, 146 Checksum .............................................................. 111
Checksum as User ID .............................................. 84
A Checksums ............................................................ 111
About...................................................................... 164 Classes .................................................................. 130
Add Existing Files to a Project ............................50, 79 Clean and Build Main Project................................. 128
Add Library and Other Files to a Project .................. 81 Clean and Build Project.................................. 128, 160
Add to Favorites ..................................................... 162 Clean Main Project................................................. 128
Add Toolbar Button ................................................ 125 Clean Only Icon...................................................... 125
Alternate Project Hex File ...................................... 103 Clean Project.......................................................... 128
Amount of Memory................................................. 111 Clear Document Bookmarks .................................. 127
Apply Code Changes ............................................. 126 Clear output window before build........................... 177
Apply Diff Patch ..................................................... 162 Clear tool output window on new session .............. 177
ASM30 Toolchain..................................................... 69 Close All Projects ................................................... 156
Assembler File Types............................................. 107 Close open source file on project close ................. 177
Attach Debugger .................................................... 126 Close Project.......................................................... 156
Code Folding.......................................................... 158
B
Code Refactoring ................................................... 112
Back ....................................................................... 158 Collaboration .......................................................... 115
Batch Build Project................................................. 160 Compile File ........................................................... 128
Breakpoint Resources............................................ 111 Compiler Support Lights........................................... 69
Breakpoints .................................................57, 88, 130 Complete Code ...................................................... 159
ANDed .............................................................. 90 Complex Breakpoint................................................. 89
Dialog................................................................ 89 Config Bits........................................................ 96, 189
Line ................................................................... 88 Configuration Bits
Number Available ........................................... 111 How To Use ...................................................... 96
Resources......................................................... 90 Memory Window ............................................... 95
Sequence.......................................................... 89 Tutorial .............................................................. 54
Software Breakpoints Supported .................... 111 Configurations, Multiple.......................................... 121
Timing ............................................................... 90 Configure Menu Changes ...................................... 153
Tuple ................................................................. 90 Connect to a Target ................................................. 31
Window ............................................................. 89 Contact Microchip Technology............................... 201
Build a Project .....................................................55, 85 Continue......................................................... 126, 161
Build Configuration..........................................146, 151 Copy............................................................... 127, 157
Build for Debugging Main Project........................... 128 CPU Memory............................................................ 95
Build Main Project .................................................. 128 Crash Logging........................................................ 124
Build Project ....................................................128, 160 Create a New Project ......................................... 39, 64
Build Properties Create a New Project File ........................................ 77
File .................................................................. 175 Cross-Platform Issues............................................ 141
Project............................................................. 175 Customer Support .................................................. 200
Build Status ............................................................ 172 Customize Zoom .................................................... 130
C Cut.................................................................. 127, 157
CVS........................................................................ 162
C Extensions ............................................................ 77
Check CVS ..................................................... 129
C File Types ........................................................... 107
Commit............................................................ 129
C++ File Type ........................................................ 107
Diff................................................................... 129
C18 Toolchain .......................................................... 69
Revert Modifications ....................................... 129
C24 Toolchain .......................................................... 69
Show Annotations ........................................... 129
C30 Toolchain .......................................................... 69
Update ............................................................ 129
C32 Toolchain .......................................................... 69
Call Graph .......................................................110, 130
Call Stack ..........................................................98, 130

 2011-2012 Microchip Technology Inc. DS52027B-page 221

MPLAB® X IDE User’s Guide
D Fill Memory............................................................. 171
Dashboard Window ........................................ 111, 130 Find ................................................................ 127, 157
Data EEPROM ......................................................... 13 Find in Projects............................................... 127, 157
Data Memory............................................................ 95 Find Next ................................................................ 157
Debug Build Configuration ............................. 146, 151 Find Previous ......................................................... 157
Debug Configuration .............................................. 122 Find Selection......................................................... 157
Debug File ...................................................... 126, 161 Find Usages ........................................................... 157
Debug Main Project................................................ 126 Find Usages Window ............................................. 131
Debug Menu........................................................... 161 Finish Debugger Session ............................... 126, 161
Debug Project ........................................................ 161 Firmware Version ................................................... 172
Debug Read ............................................................. 97 Firmware Versions, Hardware Tool........................ 111
Debug Run Code ............................................... 56, 87 Fix Code ................................................................. 159
Debug Test File .............................................. 126, 161 Flash Memory........................................................... 95
Debugger Menu Changes ...................................... 152 Focus Cursor at PC ........................................ 125, 161
Debugger/Programmer Options ......................... 47, 74 Format .................................................................... 159
Delete............................................................. 127, 157 Forward .................................................................. 159
Delete All Watches ................................................. 179 Full Screen ............................................................. 158
Desktop ............................................................ 32, 155 G
Components.................................................... 155
Go to Declaration ................................................... 158
Panes .......................................................... 45, 72
Go to File................................................................ 158
Device ID................................................................ 172
Go to Line............................................................... 159
Diff .......................................................................... 162
Go to Previous Document ...................................... 158
Disassembly Listing File................................. 110, 130
Go to Source .......................................................... 158
Disassembly Window ..................................... 110, 125
Go to Super Implementation .................................. 158
Disconnect from Debug Tool.......................... 125, 161
Go to Symbol.......................................................... 158
Discrete Debugger Operation................................. 161
Go to Type.............................................................. 158
Documentation
GPRs........................................................................ 13
Conventions ........................................................ 8
Layout ................................................................. 7 H
dsPIC Toolchain ....................................................... 69 Halt build on first failure.......................................... 177
DTDs and XML Schemas....................................... 162 Hardware Tool Selection .......................................... 67
Duplicate Down ...................................................... 159 Hardware Tools
Duplicate Up........................................................... 159 Active Connection ........................................... 177
E Help ................................................................ 127, 164
Help Menu .............................................................. 164
Edit Menu ............................................................... 157
Help Menu Changes............................................... 153
Edit Menu Changes................................................ 149
Hex File Incremental Addresses .............................. 84
Editor Toolbar..................................................... 54, 80
Hierarchy Window .................................................. 130
Editor Usage ...................................................... 54, 80
HI-TECH DSPICC Toolchain.................................... 69
EE Data Memory ...................................................... 95
HI-TECH PICC Toolchain......................................... 69
EEPROM.................................................................. 13
HI-TECH PICC18 Toolchain..................................... 69
Enable alternate watch list views during debug session
HI-TECH PICC32 Toolchain..................................... 69
177
Hold in Reset.......................................................... 128
Erase Device Memory Main Project ....................... 128
Errors ..................................................................... 143 I
Exception Reporter Window................................... 130 ICSP ......................................................................... 23
Exit ......................................................................... 157 IDE Log .......................................................... 130, 158
Experimental Terminal Window.............................. 130 Import ..................................................................... 156
Export All Watches to a File ................................... 179 Import MPLAB Legacy Project ............................... 100
Export Hex ............................................................. 174 Importing an MPLAB IDE v8 Project - Relative Paths ..
F 186
Inactive Connection................................................ 111
Favorites Window................................................... 130
Insert Code............................................................. 159
File Menu ............................................................... 156
Insert Next Matching Word..................................... 159
File Menu Changes ................................................ 148
Insert Previous Matching Word .............................. 159
File Path Options.................................................... 176
Install MPLAB X IDE ................................................ 27
File Properties .................................................. 83, 175
Install the Language Tools ....................................... 31
File Registers ........................................................... 95
Internet Address, Microchip.................................... 200
File Wizard ............................................................... 77
Files........................................................................ 128
Files Window View ................................................. 184

DS52027B-page 222  2011-2012 Microchip Technology Inc.

 Index
J N
JRE, Installing .......................................................... 27 Navigate Menu ....................................................... 158
Navigator Window .................................................. 131
K
New Breakpoint...................................................... 161
Keep hardware tool connected ...........................86, 87 New Data Breakpoint ............................................. 125
Keyboard Shortcuts, MPLAB X IDE ....................... 164 New File ......................................................... 128, 156
L New Project.................................................... 128, 156
New Run Time Watch .................................... 125, 161
Language Tool Locations....................................49, 76
New Runtime Watch .............................................. 179
Language Tools Options .....................................48, 75
New Watch...................................... 125, 126, 161, 179
Last Edit Location .................................................. 158
Next Bookmark............................................... 127, 159
Launch Debugger Main Project ............................. 126
Next Error....................................................... 129, 159
Library Files ............................................................. 81
Normalize Hex File................................................... 84
Library Projects ...................................................... 106
Licenses ................................................................. 162 O
Lights Open File........................................................ 129, 157
Compiler ........................................................... 69 Open Project .................................................. 128, 156
HW and SW Tools ............................................ 67 Open Recent File ................................................... 157
Line Breakpoint ........................................................ 88 Open Recent Project.............................................. 156
Loadable Files........................................................ 103 Open Required Projects......................................... 128
Loadable Projects .................................................. 103 Open Team Project ................................................ 156
Local History ...................................................113, 162 Output Window....................................................... 130
Locate Headers...................................................... 174
Log File ...........................................................124, 177 P
Log File Options ....................................................... 77 Package ................................................................. 174
Logging Levels ....................................................... 177 Page Setup ............................................................ 157
Palette Window ...................................................... 131
M
Paste .............................................................. 127, 157
Macro Expansion ................................................... 130 Paste Formatted..................................................... 157
Macro Recording Start/Stop................................... 157 Paths, Relative or Absolute...................................... 77
main function Pause ............................................................. 126, 161
reset ................................................................ 177 PC Profiling ............................................................ 125
stop ................................................................. 177 PDF ........................................................................ 153
Maintain active connection to hardware tool .......... 177 Peripherals ............................................................... 15
Make ...................................................................... 125 Peripherals Memory ................................................. 95
Make and Program Device..................................... 175 PIC AppIO .............................................................. 125
Make and Program Device Main Project................ 128 Plugins ........................................................... 116, 162
Make Callee Current .............................................. 126 Post-build Options.................................................... 84
Make Caller Current ............................................... 126 Pre-build Options ..................................................... 84
Make Clean ............................................................ 125 Prebuilt Projects ..................................................... 102
Make Options ....................................................84, 176 Previous Bookmark ........................................ 127, 159
make options............................................................ 77 Previous Error ................................................ 129, 159
Makefiles ................................................................ 107 Print........................................................................ 157
Memory Print to HTML ......................................................... 157
Program and Data ............................................ 13 Problem Logging .................................................... 124
Memory Gauge ...................................................... 111 Profiling .................................................................. 112
Memory Windows................................................60, 95 Program a Device .............................................. 61, 98
Memory, Type and Amount.................................... 111 Program and Data Memory...................................... 13
Menus .................................................................... 156 Program Counter...................................................... 13
Mercurial ................................................................ 162 Program Device for Debugging Main Project ......... 125
Move Down ............................................................ 159 Program Memory ..................................................... 95
Move Up................................................................. 159 Programmer Menu Changes.................................. 152
Moving a Project .................................................... 186 Programmer to Go PICkit 3 Main Project ............... 128
MPASM Toolchain ................................................... 69 Project Group ......................................................... 157
MPLAB IDE v8 Project, Import............................... 186 Project Menu Changes........................................... 151
MPLAB X IDE Installation and Setup ....................... 27 Project Properties....................................129, 157, 175
MPLAB X IDE vs. MPLAB IDE v8 .......................... 145 Debugger/Programmer ............................... 47, 74
Multiple Configurations .......................................... 121 Default......................................................... 46, 73
Multiple Projects..................................................... 119 Language Tools .......................................... 48, 75
myMicrochip Personalized Notification Service ..... 199 Project Properties Window ..................................... 130
Project Wizard......................................... 39, 64, 77, 78

 2011-2012 Microchip Technology Inc. DS52027B-page 223

MPLAB® X IDE User’s Guide
Projects .................................................................. 128 Select in Favorites.................................................. 159
Projects Window View............................................ 183 Select in Files ......................................................... 159
Projects, Multiple .................................................... 119 Select in Projects.................................................... 159
Self Test ................................................................. 161
Q
Services Window.................................................... 130
Quick Search.......................................................... 127 Sessions Window ................................................... 130
R Set Configuration.................................................... 175
Set Main Project ..................................................... 160
Read Device Memory............................................. 175
Set PC at Cursor ............................................ 125, 161
Read Device Memory Main Project........................ 128
Set PC to Cursor .................................................... 125
Read Device Memory to File .................................. 128
Set Project Configuration ....................................... 160
Reading, Recommended............................................ 9
Set Projects Folder................................................. 177
Readme...................................................................... 9
Set Up Build Properties ............................................ 84
Redo............................................................... 127, 157
SFRs .................................................................. 13, 95
Refactor
Shell Scripts ........................................................... 107
Change Function Parameter ........................... 160
Shift Left ................................................................. 159
Copy................................................................ 160
Shift Right............................................................... 159
Move ............................................................... 160
Show binary files in Project view ............................ 176
Redo ............................................................... 160
Show Documentation ............................................. 159
Rename .......................................................... 160
Show Method Parameters ...................................... 159
Safely Delete................................................... 160
Show profiler indicators during run......................... 176
Undo ............................................................... 160
Show Profiler Metrics ............................................. 158
Refactor Menu........................................................ 160
Show Toolbars ....................................................... 158
Refactor Preview Window ...................................... 131
Silent build.............................................................. 177
Refactoring ............................................................. 139
Simulator Analyzer Window ................................... 130
Relative Paths ........................................................ 186
Simulator Stimulus ................................................. 130
Release Build Configuration........................... 146, 151
SN (Serial Number) .................................................. 67
Remote Terminal Window .............................. 129, 130
Source Menu .......................................................... 159
Remove breakpoints upon importing a file ............. 177
Sources Window .................................................... 130
Remove Trailing Spaces ........................................ 159
SQL History ............................................................ 129
Repeat Build/Run ................................................... 160
SQL, Keep Prior Tabs ............................................ 129
Replace .................................................................. 157
Stack
Replace in Projects ........................................ 127, 157
HW .................................................................... 13
Reset .............................................................. 125, 161
Make Callee Current ....................................... 161
Reset Vector
Make Caller Current ........................................ 161
Reset............................................................... 177
Pop Topmost Call............................................ 161
Stop................................................................. 177
Start execution immediately ................................... 177
Reset Windows ...................................................... 164
Start Page ................................................ 32, 127, 164
Response File ........................................................ 143
Start Sampling IDE................................................. 127
Run Code ........................................................... 56, 86
Status Bar............................................................... 167
Run Debugger/Programmer Self Test.................... 161
Status Toolbar Action ............................................. 126
Run File .......................................................... 128, 160
Step Instruction .............................................. 126, 161
Run Icon ................................................................. 125
Step Into ......................................................... 126, 161
Run Main Project.................................................... 128
Step Out ................................................................. 126
Run Menu....................................................... 160, 162
Step Over ....................................................... 126, 161
Run Project .................................................... 128, 160
Step Over Expression ............................................ 126
Run SQL ................................................................ 129
Step Through Code ............................................ 58, 91
Run Time Update Interval ...................................... 179
Stop at main ........................................................... 177
Run to Cursor ................................................. 126, 161
Stop at main on reset ............................................. 177
S Stop at the Reset vector......................................... 177
Save ............................................................... 129, 157 Stop at the Reset vector on reset........................... 177
Save All .......................................................... 129, 157 Stop Build/Run ....................................................... 160
Save All Modified Files Before Running Make ....... 176 Stopwatch....................................................... 110, 130
Save As .................................................................. 157 Subversion ............................................................. 162
Scan for compilers.................................................. 176 Suppressible Messages ........................................... 77
Scan for external changes ..................................... 159 Synchronize Editor with Views ............................... 158
Search Window ...................................................... 131 T
Select All ................................................................ 157
Tasks Window ........................................................ 131
Select Identifier ...................................................... 157
Team Chat Window ................................................ 131
Select in Classes.................................................... 159
Team Menu ............................................................ 162

DS52027B-page 224  2011-2012 Microchip Technology Inc.

 Index
Team Project.......................................................... 131
Templates .............................................................. 162
Terminal Window ............................................129, 130
Test File ..........................................................128, 160
Test Project .....................................................128, 160
Test Results Window ............................................. 130
Threads Window .................................................... 130
Toggle Bookmark ................................................... 159
Toggle Comment ................................................... 159
Toggle Line Breakpoint .......................................... 161
Tool Support Lights .................................................. 67
Toolbar Customization ........................................... 125
Toolbars ..........................................................158, 165
Tools Menu Changes ............................................. 152
Trace Window ........................................................ 130
Tuple, Breakpoint ..................................................... 90
Type of Memory ..................................................... 111
U
Undo ...............................................................127, 157
USB........................................................................ 220
Device Drivers, Installing .................................. 28
User ID ..................................................................... 95
V
Variables Window .......................................59, 94, 130
Version Control ...................................................... 113
View Menu ............................................................. 158
View Menu Changes .............................................. 150
Voltages, Hardware Tool ....................................... 111
W
Watchdog Timer..................................................... 220
Watches Window ........................................59, 92, 130
Binary Formatting ........................................... 179
Char Formatting .............................................. 179
Decimal Formatting......................................... 179
Hex Formatting ............................................... 179
Web Browser ..................................................130, 158
Web Site, Microchip ............................................... 200
Window Menu ........................................................ 162
Window Menu Changes ......................................... 153
Workspaces (MPLAB v8) ....................................... 148
X
XC16 Toolchain ....................................................... 69
XC32 Toolchain ....................................................... 69
XC8 Toolchain ......................................................... 69
XML
Check DTD ..................................................... 131
Check File ................................................131, 160
Validate File .............................................131, 160
XSL Transform................................................ 131
XML File Type ........................................................ 107
Z
Zip Project Files ..................................................... 174
Zoom In .................................................................. 130
Zoom Out ............................................................... 130

 2011-2012 Microchip Technology Inc. DS52027B-page 225

 Worldwide Sales and Service
AMERICAS ASIA/PACIFIC ASIA/PACIFIC EUROPE
Corporate Office Asia Pacific Office India - Bangalore Austria - Wels
2355 West Chandler Blvd. Suites 3707-14, 37th Floor Tel: 91-80-3090-4444 Tel: 43-7242-2244-39
Chandler, AZ 85224-6199 Tower 6, The Gateway Fax: 91-80-3090-4123 Fax: 43-7242-2244-393
Tel: 480-792-7200 Harbour City, Kowloon Denmark - Copenhagen
India - New Delhi
Fax: 480-792-7277 Hong Kong Tel: 45-4450-2828
Tel: 91-11-4160-8631
Technical Support: Tel: 852-2401-1200 Fax: 45-4485-2829
Fax: 91-11-4160-8632
http://www.microchip.com/ Fax: 852-2401-3431
India - Pune France - Paris
support
Australia - Sydney Tel: 91-20-2566-1512 Tel: 33-1-69-53-63-20
Web Address:
Tel: 61-2-9868-6733 Fax: 91-20-2566-1513 Fax: 33-1-69-30-90-79
www.microchip.com
Fax: 61-2-9868-6755 Germany - Munich
Atlanta Japan - Osaka
China - Beijing Tel: 49-89-627-144-0
Duluth, GA Tel: 81-6-6152-7160
Tel: 86-10-8569-7000 Fax: 49-89-627-144-44
Tel: 678-957-9614 Fax: 81-6-6152-9310
Fax: 86-10-8528-2104 Italy - Milan
Fax: 678-957-1455 Japan - Tokyo
China - Chengdu Tel: 39-0331-742611
Boston Tel: 81-3-6880- 3770
Tel: 86-28-8665-5511 Fax: 39-0331-466781
Westborough, MA Fax: 81-3-6880-3771
Fax: 86-28-8665-7889 Netherlands - Drunen
Tel: 774-760-0087 Korea - Daegu
Fax: 774-760-0088 China - Chongqing Tel: 82-53-744-4301 Tel: 31-416-690399
Tel: 86-23-8980-9588 Fax: 82-53-744-4302 Fax: 31-416-690340
Chicago
Itasca, IL Fax: 86-23-8980-9500 Spain - Madrid
Korea - Seoul
Tel: 630-285-0071 China - Hangzhou Tel: 34-91-708-08-90
Tel: 82-2-554-7200
Fax: 630-285-0075 Tel: 86-571-2819-3187 Fax: 82-2-558-5932 or Fax: 34-91-708-08-91
Cleveland Fax: 86-571-2819-3189 82-2-558-5934 UK - Wokingham
Independence, OH China - Hong Kong SAR Tel: 44-118-921-5869
Malaysia - Kuala Lumpur
Tel: 216-447-0464 Tel: 852-2943-5100 Fax: 44-118-921-5820
Tel: 60-3-6201-9857
Fax: 216-447-0643 Fax: 852-2401-3431 Fax: 60-3-6201-9859
Dallas China - Nanjing Malaysia - Penang
Addison, TX Tel: 86-25-8473-2460 Tel: 60-4-227-8870
Tel: 972-818-7423 Fax: 86-25-8473-2470 Fax: 60-4-227-4068
Fax: 972-818-2924
China - Qingdao Philippines - Manila
Detroit Tel: 86-532-8502-7355 Tel: 63-2-634-9065
Farmington Hills, MI
Fax: 86-532-8502-7205 Fax: 63-2-634-9069
Tel: 248-538-2250
Fax: 248-538-2260 China - Shanghai Singapore
Tel: 86-21-5407-5533 Tel: 65-6334-8870
Indianapolis Fax: 86-21-5407-5066 Fax: 65-6334-8850
Noblesville, IN
Tel: 317-773-8323 China - Shenyang Taiwan - Hsin Chu
Fax: 317-773-5453 Tel: 86-24-2334-2829 Tel: 886-3-5778-366
Fax: 86-24-2334-2393 Fax: 886-3-5770-955
Los Angeles
Mission Viejo, CA China - Shenzhen Taiwan - Kaohsiung
Tel: 949-462-9523 Tel: 86-755-8864-2200 Tel: 886-7-213-7828
Fax: 949-462-9608 Fax: 86-755-8203-1760 Fax: 886-7-330-9305
Santa Clara China - Wuhan Taiwan - Taipei
Santa Clara, CA Tel: 86-27-5980-5300 Tel: 886-2-2508-8600
Tel: 408-961-6444 Fax: 86-27-5980-5118 Fax: 886-2-2508-0102
Fax: 408-961-6445 China - Xian Thailand - Bangkok
Toronto Tel: 86-29-8833-7252 Tel: 66-2-694-1351
Mississauga, Ontario, Fax: 86-29-8833-7256 Fax: 66-2-694-1350
Canada China - Xiamen
Tel: 905-673-0699 Tel: 86-592-2388138
Fax: 905-673-6509 Fax: 86-592-2388130
China - Zhuhai
Tel: 86-756-3210040
11/29/12
Fax: 86-756-3210049

DS52027B-page 226  2011-2012 Microchip Technology Inc.