I’ve been using – and, to some degree, developing – open 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:
- 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.
- 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.
- 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.
- 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.
- 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 installif you’ve followed Commandment 3 above). That’s all I ask.
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 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:
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!
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:
- Create a couple of files for autoreconf to use (Makefile.am, configure.ac, and src/Makefile.am – listings below)
- Tweak my lexer (autotools muck about with how the parser header file gets created; was an easy fix:
- Add the generated files to source control
- …and that’s it!
SUBDIRS = src
dist_doc_DATA = README
AC_INIT([svgcal], [0.1], [email@example.com])
AM_INIT_AUTOMAKE([-Wall -Werror foreign])
# programs needed
bin_PROGRAMS = parser
parser_SOURCES = svgcal.c parser.y lexer.l
AM_YFLAGS = -d