Writing Recipes
There are two ways to create recipes:
- Updating an existing one, or
- Creating one from scratch.
The utilities for accomplishing this are:
NewVersion
, EditRecipe
and MakeRecipe
.
Once the recipe is done and compiled, a packed version of it will show up in
/Data/Compile/PackedRecipes
(or the location specified in
/System/Settings/Compile/Compile.conf
.
The GoboLinux developers encourage you to contribute your recipes, so that the community can benefit.
To send a recipe for inclusion into the main Compile
tree, just run
ContributeRecipe <program name>
to submit it for review.
Setting up Compile.conf
We only need to do one thing here, add your name to Compile.conf
(for credits
on recipes you may make). Open Compile.conf
in a text editor such as nano
:
nano /System/Settings/Compile/Compile.conf
On the 2nd line of text, there should be a line for the setting
compileRecipeAuthor
. Uncomment it (remove the leading #
), and enter your
name between the double quotes.
If you have any other recipe store URLs that you want to use (friends or your
other machines), add them to the getRecipeStores
list.
Then save the file and exit nano
(Control
+O
, Enter
, Control
+X
).
Updating old recipes
When a recipe for an older version of a given package already exists, you don’t
need to run MakeRecipe
again. Instead, use
NewVersion
with the package name and version to
create a new recipe starting with the previous recipe contents. For example:
NewVersion GCC 4.4.4
This command will fetch the latest GCC
recipe, create a new subdirectory
called 4.4.4
inside /Data/Compile/Recipes/GCC
and will replace the package
version in $url
by 4.4.4
.
You can also give the full URL for the package sources:
NewVersion GCC 4.4.4 ftp://ftp.gnu.org/gcc/gcc-4.4.4/gcc-4.4.4.tar.bz2
If the version of the package has not changed, and only minor recipe updates are
needed, NewVersion
will not work as it will not
copy the same version of a recipe over. In this case,
EditRecipe
is the tool to use.
Creating new recipes
If you are writing a recipe from scratch, the “Recipe Format Specification” documentation will prove useful.
Naming new recipes
One important, but often overlooked aspect of creating a recipe is naming it.
There are guidelines and tools to ease this process, but nothing beats common
sense really: keep in mind that the name you’re giving to the recipe is the name
that will show up under /Programs
and in the binary package name. Pick names
that won’t look “out of place” in a GoboLinux setup.
You usually don’t have to worry a lot about this: Compile
and related tools
attempt to do their best to do this job for you, suggesting a name when one is
not explicitly given. But if you spot that it messed up, please abort
compilation and give it a good name as a parameter.
What’s a good name? One that follows our set of package naming guidelines:
- The app authors are sovereign about the capitalization, if they define it. Examples are: XFree86, LyX, Qt.
- If the capitalization is undefined (ie, all-lowercase) or inconsistent (for
example, showing up in different forms in the README), our set of
capitalization rules, as defined by the
NamingConventions
script, apply. - Applications are sovereign in defining their usage of hyphens and underscores to separate words in their names, when they are consistent.
- Packages should never have spaces in their names. For example, use “AdobeReader” as the name, rather than “Adobe Reader” or “Adobe_Reader”.
- There should never be two package names differing only in capitalization. The GoboLinux scripts refer to package, program and recipe names in a case-insensitive manner.
The set of rules are defined in
NamingConventions
and deal with detecting
common prefix and suffix patterns, such as “Tools” and “Utils” and
vowel-consonant heuristics.
When a program name is not explicitly given to Compile
(e.g., if it assumes it
from an URL), it passes the inferred name through
NamingConventions
. In recent versions, some
rules are enforced even in explicitly given names – one of them is that all
program names must start with a capital letter.
MakeRecipe
In this example we’ll make a recipe, starting from the source code for a program
on your computer. We’ll use joe, a text
editor (console based). This is my first recipe, and it is now in the main
Compile
tree.
MakeRecipe http://unc.dl.sourceforge.net/sourceforge/joe-editor/joe-3.1.tar.gz
Based on the filename of the URL, MakeRecipe
detects that the program it is compiling is called joe (which, after a run of
the NamingConventions
script, becomes Joe),
and that the version is 3.1.
Note
In case it didn’t, you could have passed it explicitly as parameters:
MakeRecipe HardToDetect 2.0 http://example.org/htd_2_0.tar.bz2
MakeRecipe
should now report that it has downloaded
the sources, and found that it uses autoconf. Which is a good thing, as that
means there is very little work to be done on our part. So now we compile and
install the package on our machine.
Compile joe
Wait a few minutes, and Joe will be compiled and installed on your system.
When you create a new recipe for a program that’s not yet available in the GoboLinux recipe, please consider contributing it to the community! (See section “GitHub Contributor Workflow” for details.)
TODO: Compile
‘ing progams that don’t use autoconf, ones that escape the
sandbox, etc.
Meta Recipe
Writing Meta recipe is like putting small things inside some larger container. For example consider the following meta recipe:
# Recipe for version 1.4.5 by Hisham Muhammad, on Wed Jan 23 01:28:21 BRST 2008
# Recipe (MakeRecipe) for Audacious by Andre Detsch <detsch@gobolinux.org>, on Wed Nov 30 15:01:27 BRST 2005
compile_version=1.8.2
recipe_type=meta
include=(
"Audacious-Itself--1.4.5"
"Audacious-Plugins--1.4.4"
)
Where two packages (Audacious-Itself
and *-Plugins
) are being regrouped
behind 1 “bigger” recipe called Audacious
. So with meta recipe you can have
lots of small recipes regrouped in one big recipe. It simplify installation and
can help too in some case with stubborn project that don’t get along immediately
with Gobo’s directory layout. Thus creating a meta recipes can help porting
quickly a project in one big chunk (all the parts will be installed into the
same prefix), before making it nicer and modular later.
Share your recipes
Share your recipes with the Gobo community! Recipes you create or update will be
located in /Data/Compile/Recipes
. Consider using a text editor to write a
Description file for your recipe before you share it.
To share your recipe, use this command:
ContributeRecipe <program name>
ContributeRecipe will submit a Pull Request on GitHub so that the project maintainers can review it and merge it. Please note that you will need a valid account at github.com in order to contribute recipes.
Approved committers should refer to these Guidelines (others should use
ContributeRecipe
.)