The TenFive Commandments of FOSS

I’ve been using – and, to some degree, developingopen source software for 10+ years now. Most of it was pre-packaged by the maintainers of my distro of choice, but from time to time something either wasn’t available in a repository somewhere or I needed to enable some compile-time feature that wasn’t commonly available. In short, I’ve compiled my fair share of code over the years and several Dos and Don’ts have presented themselves. Note that these are guidelines meant for those of you interested in providing software that other people will actually use. If that’s not a concern for you, feel free to ignore any/all of the below.

Without further ado, I present The TenFive Commandments of FOSS in (roughly) ascending order of importance:

  1. Thou shalt have a web presence – If all I can find Googling your project name is a SourceForge download link, I’m not very likely to want to use your software.
  2. Thou shalt provide screenshots – While it may be true that 67% of all statistics are made up on the spot, it’s a fact that adding screenshots of your software in action will increase adoption rate by 80%. Yes, even if it’s a command-line sorting program with no visible output.
  3. Thou shalt use GNU autotools – Yes, even if it’s a Java app. None of this “But it was only designed for C programs!” I’ve seen projects developed in many different languages compile and install beautifully using autotools.
  4. Thou shalt provide documentation – You’d think this would be a given. Apparently not the case. If you can’t spend an hour writing down how to use your software then why should I spend an hour poking at it randomly in a vain attempt to figure it out. …and no, “I commented the source really well!” isn’t sufficient.
  5. Thou shalt provide a README file – Such a simple, nearly universal thing…and yet I still sometimes see projects that don’t do it. This one isn’t even documentation, which can be painful and tedious to do right. A decent README file can literally take two minutes and make all the difference in the world. Tell me what your software is, why I should use it, who to contact (or where to look for help) if it breaks, and how to compile it (which should just be ./configure; make; make install if you’ve followed Commandment 3 above). That’s all I ask.
<sigh> Okay, so I was going to go for 10 commandments, but I’m having a hard time coming up with more than 5 this morning. (Need moar coffee!) I’ve got a handful of ideas kicking around in my head – portability, standards/best practices, source comments – but none of them are jumping out at me as being quite as important to the end user as the above 5. If there are any glaring omissions, let me know in the comments.
Note: I’m pretty sure I’ve broken all of the above at one point or another. Does that make me a hypocrite? 😉

svgcal now available on sf.net

This afternoon I decided to go ahead and post a project I’ve been working on “in secret” to SourceForge: svgcal. svgcal is a simple program for generating SVG calendars from a plain-text input file. An example input file looks like this:

Mon-Fri 8-8:30 commute
Mon-Fri 8:30-17:30 work
Mon-Fri 17:30-18 commute
Mon-Fri 11:30-12:15 lunch
Mon 18:15-19:15 softball
Mon 19:15-22:00 drinking
Sun-Sat 23-8 sleep
Tue,Thu 21:45-1:00 raid
Fri,Sat 21:00-1:15 drinking
Mon-Fri 8:00 wakeup

The calendar generated by this input file looks like this:

svgcal example screenshot

svgcal example screenshot

svgcal also has what I think is a novel option to generate circular calendars – daily agenda items represented as their time on the clock rather than the traditional rectangular weekly calendar. Using the same input file, one can generate a circular calendar that looks like this:

svgcal example circular screenshot

svgcal example circular screenshot

I don’t know of any other tool that creates calendars that look like this. (Note that the circular bit is a little “experimental” at the moment and not quite as pretty as I’d like it to be).

Anyhow, if you’re looking for a tool for generating SVG calendars from a plain-text agenda, check out svgcal!


Adventures with autotools

I’ve used and otherwise benefited from autotools a number of times in the past – being able to just ./configure && make && make install a large number of open source projects is hugely beneficial – but I’ve never actually ./configured (heh) one of my own projects to use them. Well…I decided to go down that path today.

The project – svgcal (link coming soon!) – is a little tool I’m throwing together to parse an input file and generate a (hopefully) pretty SVG file that displays my weekly agenda. I’m not too far along, so right now it’s just a couple of files – sources for the lexer and parser and a couple of header files – so I thought it would be good to go ahead and get autotools set up before it got much more complex than that. So, what did I have to do? Just a handful of steps:

  1. Create a couple of files for autoreconf to use (Makefile.am, configure.ac, and src/Makefile.am – listings below)
  2. Run autoreconf --install
  3. Tweak my lexer (autotools muck about with how the parser header file gets created; was an easy fix: s/y.tab.h/parser.h/)
  4. Add the generated files to source control
  5. …and that’s it!
My project is now all set up to be built using ./configure and make without me doing any additional work. Awesome!

Makefile.am:

SUBDIRS = src
dist_doc_DATA = README

configure.ac:

AC_INIT([svgcal], [0.1], [cliff@cliftonsnyder.net])
AM_INIT_AUTOMAKE([-Wall -Werror foreign])
# programs needed
AC_PROG_CC
AC_PROG_LEX
AC_PROG_YACC
AC_CONFIG_HEADERS([src/config.h])
AC_CONFIG_FILES([
Makefile
src/Makefile
])
AC_OUTPUT

src/Makefile.am:

bin_PROGRAMS = parser
parser_SOURCES = svgcal.c parser.y lexer.l
AM_YFLAGS = -d