1

Using the EE 109 Tools

Allan Weber

Mark Redekopp

2

Note and Disclaimer

• Please follow the instructions at http://ee-classes.usc.edu/ee109/project_tips.html to setup new labs/projects for your Arduino

• Some of this material is just background info that is just for reference…the stuff we'll use a lot will be repeated as we do it more and more.

3

Building a Program

• The programming/debugging loop:

– Edit [emacs, TextWrangler, Notepad++]

– Compile/Link [make, avr-gcc]

– Download and execute [make flash, avrdude]

– Observe [ you! ]

– Repeat [ you! ]

• Programs can be edited in any “plain text” editor

– Available on the VHE 205 Macs:

• Emacs (command line program)

• Vi/Vim (command line program)

• TextWrangler (Mac GUI app)

• Don’t use a word processor (Microsoft Word or Apple TextEdit etc.)

• How to start a fight: Tell another programmer that your favorite text

editor is better than theirs.

4

Editing the Program [Mac/Linux] • To run command line editors

on the Mac, start the Terminal

application from the dock at

bottom of the screen

• Emacs and Vi require some

knowledge of a few Unix-type

commands in order to be

useful (cd, ls, rm, more, etc.)

• Run the editors by just typing

the editor name and the name

of the file.

emacs myfile.c

vi myprog.c

5

Emacs Quick Reference [Mac/Linux]

• Emacs uses the keyboard for all editing commands.

• Easiest way to learn is via the built-in tutorial.

• Type the command “emacs” and then once in the editor, enter the command “ESC X help-with-tutorial”

• Read along and follow the instructions

6

Emacs Quick Reference [Mac/Linux] • Open (Ctrl-x, Ctrl-f)

– Then type in the name of the file to open or create if it doesn't exist

• Save (Ctrl-x, Ctrl-s)

• Exit (Ctrl-x, Ctrl-c)

• Cancel Command (Ctrl-g)

• Cut a whole line of text (Ctrl-k)

• Cut a segment: (Ctrl-space) at start, (Ctrl-w) at end

• Paste (Ctrl-y)

• Search (Ctrl-s) then type the word and hit enter – Hitting Ctrl-s again will go to the

next occurrence

7

Editing the Program [Mac] • The TextWrangler

text editor can be

started by dragging

and dropping the

program file onto the

icon in the dock.

8

Editing the Program [Windows] • The Notepad++ text editor

can be started by

– First selecting the file (left-click)

in Explorer

– Then right-click the selected file

and choose

'Edit with Notepad++'

9

COMPILATION UNITS

10

Compilation Units

• Often rather than putting all our code/functions in one file it is easier to maintain and re-use code if we break them into multiple files

• We want functions defined in one file to be able to be called in another

• But the compiler only compiles one file at a time…how does it know if the functions exist elsewhere?

#include <avr/io.h>

void flash(int delay)

{

PORTB |= (1 << PB5);

_delay_ms(delay);

PORTB &= ~(1 << PB5);

_delay_ms(delay);

}

flash.c

int main()

{

flash(500);

// do something else

flash(1000);

return 0;

}

flash1_test.c

11

Compilation Units • We must prototype any function we want to use

that is in another file

• Rather than make us type in the prototypes for each new program we write that needs that function, put prototypes in a header file that can be reused (included) for any new program

flash.c

void flash(int delay);

int main()

{

flash(500);

// do something else

flash(1000);

return 0;

}

flash1_test.c

#include <avr/io.h>

void flash(int delay)

{

PORTB |= (1 << PB5);

_delay_ms(delay);

PORTB &= ~(1 << PB5);

_delay_ms(delay);

}

flash.h

#include "flash.h”

int main()

{

flash(500);

// do something else

flash(1000);

return 0;

}

flash1_test.c

#include "flash.h”

int main()

{

int i=1000;

while(i >= 200){

flash(i);

}

return 0;

}

flash2_test.c

void flash(int delay);

12

Compiling to Object Code

• Two issues: – We may not want to distribute our source code files

– With a large program, we don’t want to re-compile all the files if the code only changed in one

• Solution – Compiling to object code, creates the machine code/assembly code

for just a single file BUT DOESN’T try to link any function calls to other files nor does it try to create an executable

– Use: gcc –c filename.c void flash(int delay)

{

PORTB |= (1 << PB5);

_delay_ms(delay);

PORTB &= ~(1 << PB5);

_delay_ms(delay);

}

flash.c

gcc –c flash.c

11001010101010101010101011

10101010101110101011101010

10111010101011...

flash.o

13

Linking

• After we compile to object code we eventually need to link all the files together and their function calls

• Without the –c, gcc will always try to link

• You can give gcc source files (.c files) or object (.o files)

flash.c

(Plain source)

flash1_test.c

(Plain source)

flash.o

(Machine

/ object code)

flash1_test.o

(Machine

/ object code)

flash1_test

(Executable)

gcc -g –Wall –c flash.c gcc -g –Wall –c flash1_test.c

Note: gcc -g –Wall –o flash1_test flash.c flash1_test.c

Would also work and be fine and thus not require you to

compile to object code in a separate step

gcc -g –Wall –o flash1_test flash.o flash1_test.o

14

gcc/g++ Options

• Most basic usage – gcc c_filenames

– Creates an executable a.out

• Options – -o => Specifies output executable name (other than default a.out)

– -g => Include info needed by debuggers like gdb, kdbg, etc.

– -Wall => show all warnings

– -c => compile but don't link (i.e. create an object file)

– -Ipath => add path into #include search directory

– -Lpath => add path into library search directory

– -Dmacro => #define macro

– -llibname => link in the code in library, libname

– -On => n=[0..6] => Optimization level 0-6

15

COMPILING THE PROGRAM

16

XKCD #303

Courtesy of Randall Munroe @ http://xkcd.com

17

'make' and Makefiles • We really use the 'avr-gcc' compiler (just like you use g++ for CS 103)

– But to compile for the Arduino requires many complex settings/options

– Also, a single program can be made of many source files and library code files

• 'make' is a utility program on most Linux/Unix machines which processes commands in a provided Makefile

• Helps automate compilation process – Essentially can use Makefiles as scripts of commands to be run

– Let ‘make’ fill in all the complex compilation options

• Helps provide 'smart' compilation – Compiles only files or those that depend on files that have changed since last

compilation

– Reduces wait time for compilation process especially for large programs

18

Analogy: Evaluating Expressions

• Take the equation:

– x = 5*y + (8*z + 3)

– Evaluate for y=9, z=7

– We evaluate term by term & add

• What if only y changed and we needed to find the new value of x? What would you re-evaluate

• What if only z changed, what operations would be needed to find the new value of x

19

flash.h

Smart Compilation

• Only compile code that has changed and any files that DEPEND on that code

flash.c

(Plain source)

[ CHANGED ]

flash1_test.c

(Plain source)

flash.o

(Machine

/ object code)

flash1_test.o

(Machine

/ object code)

flash1_test

(Executable)

gcc -g –Wall –c flash.c gcc -g –Wall –c flash1_test.c

gcc -g –Wall –o flash flash.o flash1_test.c

20

Compiling the Program • A 'Makefile' tells 'make'

– what files the program is composed of

– how they depend on each other

– how to compile each file (convert .c to .o or .o to an executable)

• 'make' looks at the modification dates on files to determine what

needs to be compiled, and only compiles what it has to.

Program

main.o input.o output.o

proj_defs.h

library1.a

main.c input.c output.c sub1.o sub2.o sub3.o

sub1.c sub2.c sub3.c

21

Compiling the Program • The make program uses the text file “Makefile” for

information on the dependencies (i.e. The contents of

'Makefile' is the script that tells 'make' what to do)

Sample Makefile

22

Compiling the Program • The "Makefile" for the

Lab 2 program.

• Most of it is boilerplate

and can be ignored.

• Only requires minor

changes to stuff at the

top

– Change the objects line

to contain all the file

prefixes your project

requires with a .o

extension

– Ex:

OBJECTS=flash.o

flast1_test.o

23

Compiling the Program Edit the program

lab2.c file is now newer than

the lab2.o file

Run “make”

Compiles lab2.c

Links to create main.elf

Everything up-to-date

Make doesn’t do anything

24

Downloading the Program • The make

program is also

used to

download the

binary data to

the Arduino.

• Connect the

USB cable to

the Arduino.

• “make flash” to

start the

download.

25

STOP HERE…OTHER NOTES Helpful reference but not needed…

26

CONDITIONAL COMPILATION

27

Multiple Inclusion

• Often separate files may #include's of the same header file

• This may cause compiling errors when a duplicate declaration is encountered

– See example

• Would like a way to include only once and if another attempt to include is encountered, ignore it

string.h

class string{

... };

#include "string.h"

class Widget{

public:

string s;

};

widget.h

#include "string.h"

#include "widget.h"

int main()

{ }

main.cpp

class string { // inc. from string.h

};

class string{ // inc. from widget.h

};

class Widget{

... }

int main()

{ }

main.cpp after preprocessing

28

Conditional Compiler Directives

• Compiler directives start with '#' – #define XXX

• Sets a flag named XXX in the compiler

– #ifdef, #ifndef XXX … #endif • Continue compiling code below

until #endif, if XXX is (is not) defined

• Encapsulate header declarations inside a – #ifndef XX

#define XX … #endif

String.h

#ifndef STRING_H

#define STRING_H

class string{

... };

#endif

#include "string.h"

class Widget{

public:

string s;

};

Character.h

#include "string.h"

#include "string.h"

main.cpp

class string{ // inc. from string.h

};

class Widget{ // inc. from widget.h

...

main.cpp after preprocessing

29

Conditional Compilation • Often used to compile

additional DEBUG code – Place code that is only needed for

debugging and that you would not want to execute in a release version

• Place code in a #ifdef XX...#endif bracket

• Compiler will only compile if a #define XX is found

• Can specify #define in: – source code

– At compiler command line with (-Dxx) flag

• g++ -o stuff –DDEGUG stuff.cpp

stuff.cpp

int main()

{

int x, sum=0, data[10];

...

for(int i=0; i < 10; i++){

sum += data[i];

#ifdef DEBUG

cout << "Current sum is ";

cout << sum << endl;

#endif

}

cout << "Total sum is ";

cout << sum << endl;

$ g++ -o stuff –DDEBUG stuff.cpp

30

MAKEFILES

31

‘make’ utility

• Looks for commands in a file called ‘Makefile’ or whatever is given as the –f option on the command line

• Makefile is a text file with rules (a.k.a targets), dependencies and actions along with macros if desired

rule: dependencies

[TAB] action1

[TAB] action2

• Rules => outputs; Dependencies => Inputs; Actions => commands to build the output from inputs

• To run the Makefile, we use the make command from the command prompt:

make [-f filename] [specific_rule]

• If no target specified at command line, 'all' target is made:

• http://www.eng.hawaii.edu/Tutor/Make/

32

Environment variables

• From the Linux shell (terminal) we can set "variables" that contain values that can be accessed by other programs that provide system and other info – PATH

– LD_LIBRARY_PATH

• Set with export command – export VARIABLE=VALUE

• Access value with $VARIABLE in shell

• Access value with $(VARIABLE) in Makefile

• We defined CXXFLAGS in most of your .profile or .bashrc (startup script) – CXXFLAGS = -g -Wall

33

Makefile • Defining macros/variables

– MACRO_NAME = MACRO_DEF

– SRCS = test.cpp prog1.cpp

– FLAGS = $(CXXFLAGS) # if CXXFLAGS defined by shell

• Using macros – $(MACRO_NAME)

– $(SRCS)

• Built-in Macros – $< = dependency name / name of the related file that caused the

action

– $@ name of the file to be “made” / target name

• Macro Modification – OBJS = ${SRCS:.cpp=.o}

• Substitute .o for .cpp wherever it occurs in the expansion of SRCS

34

Example • Example

– wget http://ee.usc.edu/~redekopp/cs104/makeex.tar

– tar xvf makeex.tar

– cd makeex

• test1: foo.cpp bar.cpp test1.cpp

• test2: bar.cpp list.cpp

• Two Makefile

– Makefile.basic

• Just hard code dependencies

• I might suggest you go this route for your assignments…easier for now

– Makefile.inter

• Intermediate: uses some substitutions to be more general

src

proj

include

build

common

src

foo.cpp

foo.h

list.h

list.cpp

bar.cpp

test1.cpp

bar.h

test2.cpp

Put your .o &

exec here