A good example are Maven (mvn install) or most automake builds (configure && make && make install). They usually just work and if they fail, they give you some context to work from.
A good negative example are Eclipse PDE builds: Often there is no build script. If there is a build script, it will fail with an obscure error message in an Ant script that was recursively called by about 100 other Ant scripts. Each Eclipse project uses PDE but each build has different prerequisites (which you must know). If the build uses p2 repositories, there is no way of telling whether two subsequent builds will produce the same result. Some projects try really hard to help newcomers to build their stuff with a recipe that needs 100+ easy steps. In four words: It’s a mess.
Or a surefire way to attract only the most dedicated committers because everyone else will be utterly demotivated very quickly (and you don’t want those, do you? 😉
Why a script and not, say, a web site with instructions? Several reasons:
- A script will make you more dedicated. It’s easy to be sloppy with a README. With a script, at least the syntax will be right.
- When a README fails, you won’t really know what to do next. With a script, you have a very precise starting point for a bug report: “The setup script failed in line 15” vs. “Install with Maven … and which version?”
- Scripts can prepare the environment. Since you don’t want to make anyone angry, create a new directory and put everything in there. Download what you need, unpack it, configure it. If you can’t do it with a script, why should a newcomer fare better?
- Can’t download something? You can always print an error message with exact instructions: Go to website … download xxx, version yyy … put it here. In a script, you can say ‘echo “Put download into $build_dir”‘ Try that in a README.
- You can prove that a script works. Good luck trying that with a README.
- You can run scripts on a CI server to make sure they work.
- A script always needs an interpreter. Bash scripts run on Mac and Linux. What about Windows users? Well, 100% of the Windows users build OSS software from .msi files. The tiny rest has three options: a) Read the bash script, b) install Cygwin/MinGW, c) install Linux.