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.

As hard as it is, I try to keep my resume, cover letter, and letter of references up to date. It gives me an idea of how my skill set is growing over time and also keeps me relatively in tune with what the job market looks like for Software Engineers.

Several months ago, while going through the motions of updating my resume package, I realized that I didn’t have an up to date coding sample. So began the process of becoming intimately familiar with the Byzantine Generals Problem. For a great analysis of the problem and one potential implementation, check out
Mark Nelson’s post on this very problem.

Although Mark provides his own sample C++ implementation, I went in a slightly different direction and leveraged a few APIs, tools, and technologies that I’ve been meaning to try in a project for some time.

I version controlled my solution to this problem: C++ coding sample on BitBucket and also uploaded the associated Doxygen Generated Documentation.

I’ll likely spend a few posts talking about some of the neat things I ran into along the way, but please take a look and don’t hesitate to leave some feedback!

Update for additional parts:

• Byzantine Generals Coding Sample, Part 2 (Makefiles)

This is a follow up to a previous post about GitHub. While Git + GitHub have worked relatively well for my needs, I’ve found one deal breaker that’s missing from GitHub: http push. Http push simply means that you can commit your changes to a given repository over native http. That is a must have, since most of the time I sit behind a rather pernicious corporate firewall.

Lately, I’ve been reading about Mercurial, which in many ways is very similar to Git. For some good reference on the differences, check out this Stack Overflow question. If you’re interested in learning Mercurial (Hg), check out the tutorials at HgInit. It turns out there are some very similar services to GitHub for Mercurial, one of which is BitBucket. As you’ve probably guessed by now, the first listed feature of BitBucket is both http push and http pull. So, I used the built in git-mercurial conversion utility and moved my stuff over and have been happily coding away.

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.

A good friend of mine recently pointed me to an excellent article over at Gamasutra : Book Excerpt: Game Engine Architecture. I liked the excerpt so much that I picked Game Engine Architecture up a few weeks ago. I’m slowly making my way through it, and will have a full review once completed.

Here are some initial thoughts:

• The book is well laid out, with a brief introduction on C++ programming for those that are unfamiliar.
• The book acts as a great jumping off point to further reading. Each topic covered has in-line references to much more in depth coverage of said topic.
• The book is a terrific high level overview of the common problems encountered in Game Engines (Soft real time systems).

One other quick note: even if you work mostly in hard real time systems, as I do, I think you’d be surprised at how useful it is to read about other programming domains. As computer scientists and programmers, we all run into the same sorts of underlying problems. Solutions that work in one domain can often be modified to apply to other domains.

Despite all of the controversy and at the great insistence of my best friend, I bought a copy of Call of Duty 4: Modern Warfare 2 (MW2) for the PC. Let me start by saying that the game is nigh onto being a masterpiece. Despite several shortcomings, of which I will enumerate several below, it is quite the gaming experience. Having missed out on the first Modern Warfare, I can’t really compare it to that cherished title.

Several other places on the web have listed all of the issues dealing with the PC version of MW2. Most of them center around the fact that the multiplayer experience is essentially gimped on the PC. The root of the problem is that most PC first person shooters created in the last decade have allowed users to set up dedicated servers. That model has been perfected because it works for a number of reasons, most important of which, is that it builds strong communities.

For a modern PC gamer, finding a good server where you like to play is a little like finding the mythic bar from Cheers. When you play on the same server for a long amount of time, you get to know the admins, you see and recognize other players, you may get involved in the local clan, and so on. In other words, you build a micro-community around that server. I can appreciate when a developer tries to innovate gaming experiences. In this particular case, within a couple of clicks, you can easily get into a MW2 multiplayer game. The problem is that those games might as well be against AI opponents. There is rarely any team communication, you can never guarantee your gaming experience because hosts are automatically chosen, and most importantly, you never play with the same people more than a few games in a row. Imagine for a moment an alternate history: in addition to the current implementation being available as a “Quick Game” feature, IW released full dedicated servers to users. Within weeks, there are thousands of servers in the world, many of which host local clans. At each one of those servers, micro-communities are created. The communities encourage organized competitive play, and suddenly, you have a market longevity that far outlives the Quick Game.

So, despite these glaring shortcomings, IW has poured a significant amount of love into this game. The single player experience feels like you’re the hero in an action movie. It’s short, but quite gratifying. Concerning multiplayer, there are a plethora of things to like:

• There are many, many types of game modes – all of which are interesting.
• Significant diversity in weapons and weapon modifications, which unlock as you gain levels and use the weapons.
• Games are fast paced, intense, and fun.
• It is easy to find and get into a multiplayer game.
• Graphics and sound are stunning.

Overall, the game is definitely worth buying. I truly hope that IW takes some of these criticisms to heart and releases dedicated servers; but the lack of which isn’t worth you missing out on this title.

I was a big fan of the first Left 4 Dead. It was sort of the perfect storm consisting of four player co-op, zombies, and addictive gameplay. Although there was a lot of controversy surrounding the announcement of the second game so soon after the first was released, I don’t subscribe to such silly notions. It’s quite ironic that the same gamers who complain that a game is taking forever to get released are upset when a perfectly good follow up is released sooner than expected, but I digress. The heart of the matter is this: Left 4 Dead 2 stands on its own two feet by surpassing the first in every meaningful way. More weapons, more zombies, more campaigns, more game modes, and more fun. Add to this the fact that you and three of your friends can get it as part of a valve 4-pack ($150 / 4 copies); there really isn’t any reason you shouldn’t pick up a copy.

Now, if you will kindly excuse me, I need to move. Everyone knows that if you stay in one spot too long, the zombies will find you.