Ever so often someone new to Open Source show up on GitHub or in my inbox. It usually starts something like this:
- “Hey, I just downloaded your software, what’s next?"
- “Your software doesn’t work on my system!!!!"
- “How can I do that weird-thing that fits my odd use-case?"
- “I have zero documented experience but I think you should fix your build system!"
This HowTo is for you.
0. Short Version
- Download a versioned archive from the project’s Releases page
- Extract archive for v1.2.3 and change to its directory,
./configure --help, or use something like the following …
./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var && make && sudo make install
Some projects of mine are available in Debian/Ubuntu/FreeBSD, if you use that, please report bugs to them and not me. I have no control over what they do.
1. I don’t owe you free support
Just because the software is published for free, and often without any restrictions1 on use, doesn’t mean I must provide you with any (free) support.
If you use my software packaged by a 3rd party, e.g., Debian, FreeBSD, or similar, please report the bug/problem to them first. They become first line support when publishing my work.
2. Use released software, not GIT sources please
There are some important caveats to consider if you’re new to Open Source software:
- Released software is stable software, use versioned tarballs/zip files
- Software in GIT may be missing important files/scripts
- Software in GIT, even on the master branch, may be unstable or unfinished
- Only use GIT sources if you know what you’re doing and want to contribute
When I release software on GitHub I first do a “tag”, then build the release from that tag. This results in artifacts such as an archive in the form of a tarball, or zipfile, with a version in the name.
GitHub has the bad habit of automatically creating archives for a “tag”, don’t use those. They typically miss important files.
Released archives, in most of my projects, include a
which usually is not available in raw GIT.
Every project on GitHub has a Releases Page, e.g.
Unless you want to contribute to the project, use released software!
3. Some assembly required
Pun intended, but don’t worry I don’t use any assembly language in my software. It’s more like building furniture from IKEA.
As mentioned previously, and for reasons between different operating systems, as well as to facilitate cross-compilation to embedded targets (biggest audience by far!), most of my projects include a configure script. This script is generated at release time and is not available from GIT sources. (See below for how to build from GIT sources.)
From the project release page, download the versioned archive (means
it has a version number in the name and ends in tar/zip) which includes
the configure script, extract the archive, run the
and then run
Other requirements is a C compiler (I’m old so that’s still my jam) and the header files and .a file(s) for the C library in you system. Some of my projects also have other requirements, see the README file or the output from a failing configure script for details.
wget https://github.com/troglobit/ssdp-responder/releases/download/v1.7/ssdp-responder-1.7.tar.gz tar xf ssdp-responder-1.7.tar.gz cd ssdp-responder-1.7/ ./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var make
When that is done you have the built
ssdp-scan tool and the
daemon (UNIX service) available in the
src/ directory. You can now
either run the programs from there, or install them on your system
This installs them into the default prefix
/usr/local, which you can
change by supplying a different prefix path to the configure script.
./configure --help for details.
4. Building from GIT
I always recommend users to run released software. However, sometimes new features are not released yet, or (new) users want to try out the latest upcoming software.
- In 95% of the cases you need
automake. Sometimes you also need (GNU)
libtool, sometimes more tools are required, see the README for each project for details.
- Usually I never put generated files under version control. This
configureet al is not available in GIT.
configure, for projects that use the GNU Configure & Build
When refreshing your
git clone with
git pull, you may have to run
autogen.sh script again, but most of the time
make handles this
5. A note on paths
configure everything is about
--prefix. Everything is derived
from that path, which traditionally defaults to
/usr/local. A few of
the default directories are listed here:
prefix = /usr/local # default, use --prefix=/foo sysconfdir = $prefix/etc datadir = $prefix/share docdir = $datadir/doc/PACKAGE localstatedir = $prefix/var runstatedir = $localstatedir/run # only in recent autoconf versions
All of the above (except
$runstatedir, depending on autoconf version)
are possible to override from the configure script. For details, see
the usage text with:
Most, if not all, of my projects use these directories also in the
$runstatedir (or equivalent) is used for
PID files and
see the file LICENSE or COPYING included with the software. ↩︎