Module Guidelines

Revision as of 20:40, 30 June 2009

Generic

These guidelines apply to all of a module's files.

• Never use tabs. Use spaces instead.
• Use 72 columns as a maximum width whenever possible (but always in the long description in the DETAILS file!).
• Respect the MAINTAINER value. Don't modify maintained modules unless you first consult the listed maintainer.

DETAILS

• Always use a SHA1 checksum instead of a MD5 checksum for SOURCE_VFY values.
  • The SHA1 algorithm has been shown to be less prone to key clashes than the MD5 algorithm.
• Don't insert your eMail address into the MAINTAINER field unless you are a Lunar developer.
• Prefer tar.bz2 over tar.gz tarballs (as it saves space/traffic) and prefer tar.gz over zip (or rar) packages.
• Avoid using the module's name in the SHORT field.
  • e.g. instead of SHORT="MyModule is an application designed to take over the world." you should use SHORT="an application designed to take over the world"
  • You are encouraged however to start the long description off with the modules name. So in the example above the long description might be "MyModule is a GTK+-2 application designed to take over the world. It features mind-control and cute, fuzzy kittens." (wrapped to 72 characters characters of course.) This way the output of lvu what is presented nicely to the user.
• Always align the equal signs (=) vertially within the file. "=" should be at character position 17, as this allows for the (optional) variable SOURCE_DIRECTORY= to be added later if needed and have it still be lined up with the rest of the content already in the file.
• Make sure to check whether a module is PSAFE or not. A lot of programs fail to build with parallel makes.

• If the module is a development version downloaded from a source code management system, rather than a release tarball:
  • the module should be in the zbeta section of the moonbase.
  • VERSION should be set to beta, cvs, git, svn, or similar.
  • UPDATED should not be a fixed date, but should be generated using `date -u +%Y%m01` or similar. An explicit lin myModule will automatically update the source code from the repository, but lunar update will not trigger another download and rebuild until the generated date changes.

DEPENDS

• Only list unique dependencies.
  • That means that if the module you are building requires both "libX" and "libY" to properly compile/run but "libX" itself already requires (non-optionally) "libY," you should only add "libX" as a dependency to your module. This is because "libY" will automatically come along with "libX."
• Never put logic into this file. The only things that can exist in this file are function calls to depends and/or optional_depends.
  • Putting logic into DEPENDS, while it might seem clever, is a sure way to mess up Lunar's internal dependency handling mechanisms and commands such as lvu leert.
• If possible, always provide the means to disable support for an optional dependency, even if that optional module is installed.
  • That means if the application's ./configure script allows for a --disable-my-optional-depends you should include that switch when building your optional_depends line. This allows you to not compile in support for certain features, even if your computer has the necessary application/library installed to support that feature. Remember, choice is good.
• Do not use '&&' delimiters to separate multiple depends and optional_depends calls.
  • Old modules used them to be consistent with BUILD files, but they are not required. New modules should not use them.

CONFLICTS

• Remember to add a CONFLICTS to both modules that conflict with each other.
• When removing/renaming a module that had a CONFLICTS file, remember to remove/rename the conflict on all of the other modules this module conflicted with. Don't leave orphaned conflicts.

CONFIGURE

PRE_BUILD

BUILD

• Don't create "here" documents in BUILD as input to patch.
  • Create a separate patch file instead.
  • Set SOURCE2 in DETAILS as if the patch were an additional source file.
  • Set SOURCE2_URL to $PATCH_URL
  • Copy the patch file to /var/spool/lunar during testing.
  • Remember to send it to the mailing list at lunar-dev (at) lunar-linux (dot) org, or include it during lvu submit.

• Don't install files after calling devoke_installwatch.

POST_BUILD

• Don't install any files into the system.

POST_INSTALL

• Don't install any files into the system.

PRE_REMOVE

POST_REMOVE