ZenSRC

Just a quick post. I’ve added a permanent Library page (currently accessible on the right column). I thought it would be good to keep track of the books I have so I can easily recommend/reference them to other people. I’m also hoping it will keep me honest in writing down my thoughts after I complete each book (again or for the first time). I feel like the best books are the ones that teach you something every time you read them; these definitely reaffirm that idea.

This is a follow up article to my C++ Byzantine Generals Coding Sample which focuses on the Makefile part of the project.

Over the years, I’ve heard many complaints directed at Make and Makefiles (and I’ve done a bit of it myself). I think the biggest problem coders have with Makefiles is that they are nearly a black art in and of themselves. I think most programmers would rather spend time on the actual code they write than on figuring out the sometimes complex syntax that gets their compiler to build their source files in an efficient manor.

This post is intended to pull together some of the best practices I’ve found and to discuss some of the neat tasks that I have my Makefile doing in the hopes that it helps get you to a solution faster.

First up, the help target. You’ll notice in the full Makefile that the help target appears first. Many makefiles typically have “all” first, which usually makes the default behavior perform a complete build. I’ve found that printing usage information on the available targets far more preferable. It gives new users an idea of what the makefile does, and what to expect from each target.

.PHONY: help
help:
	@echo 'Commonly used make targets:'
	@echo '  all          - build program (use release and debug targets instead)'
	@echo '  check        - build program and run valgrind memory check tests'
	@echo '  clean        - remove files created by other targets'
	@echo '  debug        - build program with debugging enabled and optimizations disabled'
	@echo '  docs         - run doxygen to produce documentation'
	@echo '  graph        - build program and run, generating output graphs'
	@echo '  print        - creates a pdf listing of the source code'
	@echo '  release      - build program with debugging disabled and optimizations enabled'
	@echo '  TAGS         - build TAGS database for source code'

Next, we provide targets for release and debug. All we’re doing here is modifying the $(CFLAGS) variable such that it uses the correct compilation flags for the relevant target. These get modified and passed on to the “all” target and that way we keep the rest of the rules clean.

#
# We use target-specific variable values for debug and release build targets,
# see <http://www.gnu.org/software/make/manual/make.html#Target_002dspecific>
#
.PHONY: debug
debug: CFLAGS += $(CDEBUG)
debug: all

.PHONY: release
release: CFLAGS += $(CRELEASE)
release: all

Next up is the heart of the compilation part of the makefile. This line literally says that for each of the object files we need to build, use the corresponding C++ (.cpp) file from the source directory. Prior to constructing and passing the compilation line to the shell, we perform static code analysis on our input source files. Essentially, we’re stacking the deck in our favor by attempting to catch subtle errors early and often. In the event that the static analysis tool (cppcheck) finds anything, it will force the compilation to halt and require the developer to address the relevant issue. Finally, I found a great resource concerning correctly generating the list of dependencies, and thats where the dependency generation lines originate.

# Simple brute force rule to build obj/*.o based on their src/*.cpp counterparts
# Dependency generation reference <http://make.paulandlesley.org/autodep.html>
#
# Also perform static analysis on all of the files, in another effort to
# stack the deck in our favor and catch errors early (Force our static
# analysis tool to return an error and halt the makefile when it finds
# problems).
.PHONY: $(objdir)%.o
$(objdir)%.o: $(srcdir)%.cpp
	@mkdir -p $(dir $@)
	@echo "============="
	@echo -n "Static analysis: "
	cppcheck -q --error-exitcode=1 $<
	@echo "Compiling $<"
	$(CC) $(CFLAGS) -c $< -o $@
	@echo "Dependency generation $<"
	@cp $(objdir)$*.d $(objdir)$*.P; \
		sed -e 's/#.*//' -e 's/^[^:]*: *//' -e 's/ *\\$$//' \
		-e '/^$$/ d' -e 's/$$/ :/' < $(objdir)$*.d >> $(objdir)$*.P; \
		rm -f $(objdir)$*.d

This next target, “check” is fairly straight forward, but immensely useful. It runs the excellent Valgrind memory analysis and profiling tool over our project. Ideally, this would be incorporated into a batch of automated unit tests, but more on that later. It’s enough to say that we’re taking another step towards detecting issues early and often by providing a common and simple way for all developers to run this tool via the make system.

.PHONY: check
check: debug
	@echo "============="
	@echo "Performing valgrind analysis"
	valgrind --track-origins=yes --leak-check=full $(TARGET) $(TARGET_BASE_ARGUMENTS)

Another simple target is the automated generation of Doxygen documentation. I have the Doxyfile set to spit out warnings to a text file, doxy_warn.txt, so the developer can visit it after the make process and take care of any issues that were found. Doxygen is an immensely useful tool, and when leveraged correctly, can make the process of providing API documentation to third parties especially nice. Here is the doxygen documentation that my coding sample generated.

.PHONY: docs
docs: graph
	@echo "============="
	@echo "Creating Documentation using doxygen"
	doxygen ../doc/Doxyfile
	cat ../doc/doxy_warn.txt

Finally, the “TAGS” target. Exuberant Ctags is another terrific development tool that allows developers to quickly navigate source code. I have the TAGS target rebuilt on “all”. This keeps our source code database fresh.

# Do not add phony rule, we want TAGS to be checked to save a little build time.
TAGS:
	@echo "============="
	@echo "Creating TAGS"
	etags -o $(srcdir)TAGS $(srcdir)*.cpp  $(srcdir)*.h

So here are a few things that this makefile doesn’t do, which it normally could. These aren’t done mostly because the coding sample I wrote didn’t require it.

• Automate unit testing (run unit tests, verify passage, generate and distribute reports).
• The makefile isn’t setup to do builds which require multiple components built across multiple directories.
• Doesn’t perform installation.
• Doesn’t dependency checks.

Occasionally, I’m asked to interview new college graduates for software engineering positions at my company. Over time, I have accumulated what I believe to be a good set of interview questions that check breadth of knowledge more than depth. I do spend time digging into depth for what the interviewee feels they are strongest at just to make sure they do indeed know what they claim to. This question on Stackoverflow caught my eye yesterday, and the top rated answer took me to the the Programmer Competency Matrix. This table is a terrific reference for testing programmer’s ability and I haven’t seen anything else that’s quite so concise yet covers so many of the bases.

A friend of mine sent me a link to a great video about motivation, entitled “The surprising science of motivation” by Dan Pink. The video focuses on what it takes to motivate people in a workplace and contrasts mechanical labor intensive jobs versus cognitive labor intensive jobs.

What I particularly like about this video is how Dan analyzes the problem of motivating workers who spend their time doing creative, cognitive work. The science says that once you “pay people enough to take money off of the table” then there are three factors that lead to better performance and personal satisfaction:

• Autonomy – A person’s ability to self-direct his/her tasks.
• Mastery – A person’s feeling that they are learning, growing, and finding new and better ways to perform their jobs.
• Purpose – The feeling that a person has that his/her product is making the world a better place.

Most businesses still fail to realize that it isn’t about pay incentives. It’s about making people feel like they own the products they produce. This is one of those TED videos that rings true. In my own experience, I have had all three during one time or another in my career and I can honestly say that during those periods of time when I felt all three, work ceased to feel like work, and it felt more like play. Check out the video.

A couple of years ago, Apple introduced a little device called the iPhone. It revolutionized smart phones for several reasons, highest amongst them the ability to have a usable web browser in your pocket, the ease of adding and removing other applications, and, of course, the built in iPod capabilities.

A few days ago, Apple unveiled their newest creation, dubbed the iPad. Having only tuned into Apple’s press event and read the subsequent impressions of the device; I thought I would add my thoughts to the maelstrom of opinions. Rather than try and cover all of the ground that other blogs and reviews have covered, I’ll stick to the primary reason why I was disappointed by the initial announcement: the complete lack of a camera.

Normally, I wouldn’t care if a phone or portable device contained a camera; but in this particular case, it seems like such a major oversight as to make you stand back and scratch your head in wonder. Let me setup a hypothetical situation for you: Your iPad sits on a stand in your living room pretending to be a digital photo frame when an incoming Skype phone call comes in. Your iPad switches with typical elegance to a photo of the caller with a large answer button. You tap said button, and now you’re in a video call with the other party. That’s a revolution. I suggest it as differing so far from the norm (audio only) and such an improvement in the quality of communication that it is simply akin to moving from the radio to television. For $500, I could have seen many families buying them to keep in touch with long distance loved ones.

I suppose it’s still good for browsing the web, listening to music, and installing other applications. Come to think of it, maybe I’ll just stick with my iPhone…

Update: Penny Arcade hit the nail on the head.