Introduction

One of the purposes of this course is to learn the basics of the C programming language. Towards that goal, we will begin the course by writing some simple C programs that are built to run on a computer alone, and not any sort of microprocessor. This section will guide you through setting up a C-language compiler and an integrated development environment or IDE.

Note that if you already have a compiler and/ or IDE that you are comfortable and experienced with this page may be of little use to you.

Setting up a compiler

Unlike some languages that you may be familiar with (MATLAB for one) the C programming language must be "compiled" before it can be run on the computer. A compiler's job is to take the code that a person writes in the C-language and convert it to a "binary file" in machine language that the computer understands. For more info see wikipedia.

The compiler that we recommend is the GNU Compiler collection or GCC. This is a widely used cross-platform compiler toolsuite that has libraries and compilers for C, C++, Fortran, Java, and more. Additionally the compiler that we will use later on in the course for compiling C code to run on the PIC32 is based on GCC.

In the next section we are going to discuss setting up an integrated development environment (IDE) called NetBeans. They have very thorough directions for setting up the GCC compiler on every operating system here.

Windows

Windows is arguably the most difficult operating system to get the compiler working with. The GCC toolsuite was originally developed to work with Unix/Linux operating systems, but there are two popular Windows ports available, Cygwin and MinGW.

MinGW is probably the easier of the two to setup so that is what we recommend. Complete, detailed instructions for this process can be found here.

A quick summary of these steps is provided in the following:

Install MinGW-5.1.4.exe (direct link).
Add C:\MinGW\bin to the system path by editing your system's Environment Settings.
Install MSYS 1.0 files by running MSYS-1.0.10.exe (direct link).
Install the gdb debugger by downloading gdb-6.8-mingw-3.tar.bz2 (direct link) and extracting using WinZip, gzip, or 7-zip such that the gdb executable is in the C:\MinGW\bin directory.

Apple OSx

To get all of the required tools you must install Xcode and X11 from the Apple Developer Connection. Note that you must sign up for a free ADC membership.

Linux

Many linux distributions have GCC bundled with the install, if you do not have it you should be able to get it from your distribution's repositories using your favorite package manager.

Setting up the IDE

Now that you have a compiler, all you really need is a text editor, and you are ready to start coding in C. However, learning the ins and the outs of compiling, linking, debugging, Makefiles, etc. can be a bit overwhelming. So we are going to recommend the use of an IDE to help you get started. As well as helping beginners, many experienced programmers do all of their development in an IDE. An IDE can act as a source code editor, it can provide graphical interfaces to debuggers and compilers, it can autogenerate useful configuration files, and many more useful features. The IDE that we are going to recommend is NetBeans. NetBeans is totally free, it is cross-platform, and Microchip has paired with NetBeans to develop their new-generation IDE for PIC development, MPLABX (which you will be using later in the course).

To install NetBeans simply visit this link and install either 6.9.1 or 7.0.1 for your operating system. You can install either the full version, or just the C/C++ version (recommended). Note that this doesn't really matter as modules can be added or deleted later on.

More detailed tips on configuring and troubleshooting can be found here.

A decent tutorial on setting up and configuring C/C++ projects within NetBeans can be found here.

ME333 Customization

In this course we plan on using two spaces for an indent, and no more than 80 characters per line. To set these options in NetBeans do the following:

click "Tools>Options"
Then select "Editor" from the buttons at the top
Then select the "Formatting" tab
Set "Languages" to "All Languages"
1. change "Number of Spaces per Indent" to 2
2. "Tab Size" to 2
3. "Right Margin" to 80
4. make sure the checkbox for "Expand Tabs to Spaces" is checked
5. "Line Wrap" is set to "After words"
Then set "Language" to C, and make sure that the "Override Global Options" checkbox is unchecked.

Test Programs

Step 2 configuration.

Screenshot of step 3 configuration.

In this section, we are going to create a very simple project in NetBeans, and then compile it and analyze the output using a few different techniques.

First open NetBeans, and click File>New Project
Select C/C++ Application
Configure project as shown. Be sure "Create Main File" and "Set as Main Project" checkboxes are selected, and that the language of choice is C (not C++). Also be sure your compiler is selected under "Tool Collection."
Locate the "Projects" window. If it is not already visible, you can select it under the Window menu at the top of the screen.
Clicking the plus next to "Source Files" in the project window should reveal a file called "main.c". This is basically a blank C source code template that you can work from. Open this file by double clicking on it.
Edit the "main" function so that it looks like the following:

     int main(int argc, char** argv) {
       printf("Hello World!");
       return (EXIT_SUCCESS);
     }

Your project is now created, and we will look at a couple of different ways to compile and run it.

Using the IDE to compile

To compile the code you can click "Run>Build Main Project". Note the text that is printed in the "Output" window. If no errors are printed and you see something like

     BUILD SUCCESSFUL (total time: 2s)

then everything worked and you are ready to run the code. Clicking the green triangle button, or "Run>Run Main Project" will actually run the code. You should see something like

     Hello World!  
     RUN SUCCESSFUL (total time: 144ms)

printed in the "Output" window. If all of this worked, you have just written, compiled, and ran a test C program.

Note that there are several output files that are created by this compilation process. In your project directory there are two subdirectories called "build/" and "dist/". Inside of the "build/" directory are the so-called object files generated by the compiler. These are essentially just machine code versions of the raw source code that you wrote. Inside of the "dist/" directory, you will find an executable file that is actually capable of running on your system. For example, on a Windows machine that followed all previous instructions, you will find the following file

   <PROJECT_DIRECTORY>\dist\Debug\MinGW-Windows\helloworld.exe

This executable can be run just like any other executable on your system. Note that in OSx or Linux there will not be a ".exe" extension on your executable. The compiler name found in the above directory may vary as well.

Command Line Usage

To further analyze what just happened we are going to do a couple of things from the command line. In your OS, open a command line. In OSx this is called "Terminal" and in Windows this is called cmd (Click "Start>Run" then type cmd and hit enter).

Let's start by simply executing the file generated by the previous compilation. So we are going to navigate to the aforementioned executable output directory of the project. Note that the command "cd" will allow you to change directories. So for example on Windows you might type something like

     cd C:\Users\<USERNAME>\Documents\NetBeansProjects\HelloWorld\dist\Debug\MinGW-Windows

or on OSx or Linux I might type something like

     cd /home/<USERNAME>/NetBeansProjects/dist/Debug/GNU-Linux-x86/

where you must replace <USERNAME> with your username.

Typing "ls" in the command line will then print the contents of the current directory. Note that in Windows, "ls" is not part of the normal command line interface, but earlier when we installed MSYS, we enabled this. If for some reason "ls" does not work to print the directory contents, try typing "dir". Printing the contents of the output directory should reveal just one executable file, "helloworld.exe" (Windows) or simply "helloworld" (Linux/OSx). Let's run that executable now so we can see its output. On Windows simply type "helloworld.exe" (no quotes) into the command line and press enter; in OSx, type "./helloworld". You should see "Hello World!" echoed back to you.

Now let's attempt to compile this file by invoking the compiler manually. We want to navigate to the base project directory. On any OS that can be accomplished by typing

     cd ../../../

Note that here the ".." implies the parent directory of the current directory. Now we are ready to compile the file using GCC. On Windows we can type

     gcc.exe -o helloworld.exe main.c

or on OSx you can type

     gcc -o helloworld main.c

This will generate a new executable file in the current directory called "helloworld(.exe)". This can be executed as we just did above. Note that the "-o" in the above commands is an option telling the compiler where to generate the output. There hundreds of different options that can be passed to the compiler and many different configurations for how projects are compiled. It can be quite confusing! This is one of the things that the IDE does for you. It sets all of these options either automatically or through graphical interfaces.

Makefiles

Note that in the project base directory there is a file called "Makefile." This file combined with several other "Makefiles" in the nbproject directory is where all of these options are stored. One of the programs that was installed earlier when we setup a compiler is called "make". Its job is to read the configurations stored in "Makefiles" and call the compiler accordingly.

On complicated projects, compiling can take a very long time. One of the main features of "make" is that before it compiles anything, it looks at what files have changed since compilation last occurred. It then compiles only the files that must be recompiled to reflect changes. This can significantly increase compilation speed. "Make" is what NetBeans is actually calling when you are clicking "Build" or "Clean and Build".

We can invoke it from the project base directory by simply typing the word "make" in the command line. The printed output should be the same thing that you would see if you opened NetBeans and clicked "Run>Build Main Project".

Other Sample Code

We have provided several other sample pieces of code to facilitate learning the C-language. The first you should look at can be found here, and a slightly more complicated piece of code can be found here. Each of these can be compiled by creating a new NetBeans project as described above except this time you will want to uncheck "Create Main File." To add one of the downloaded example codes to your project simply alternate click (right click Windows, Ctrl+click OSx) where it says "Source Files" in the "Projects" window and select "Add Existing Item...". Once the file is added to your project you should be able to build and run it using the instructions from above.