Module Guidelines

From Lunar Linux
(Difference between revisions)
Jump to: navigation, search
(Use spaces rule added)
(DEPENDS)
 
(55 intermediate revisions by 7 users not shown)
Line 1: Line 1:
 
__TOC__
 
__TOC__
  
== Rules ==
+
== 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.
  
=== Generic ===
+
== DETAILS ==
  
* '''Never''' use tabs. Use spaces instead.
+
* Always use a SHA1 checksum instead of a MD5 checksum for SOURCE_VFY values.
 +
**The SHA1 algorithm has been [http://news.com.com/Crypto+researchers+abuzz+over+flaws/2100-1002_3-5313655.html 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 <code>SHORT="MyModule is an application designed to take over the world."</code> you should use <code>SHORT="an application designed to take over the world"</code>
 +
** 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 <code>SOURCE_DIRECTORY=</code> 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.
  
=== DETAILS ===
+
* 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 ===
+
== 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 eert''' and '''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.
 +
* Use '''lvu links''' to help determine depends.
  
=== CONFLICTS ===
+
== CONFLICTS ==
 +
* Remember to add a CONFLICTS to both modules that conflict with each other.
 +
** Use '''lvu conflicts''' to help determine conflicts.
 +
* 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 ===
+
== CONFIGURE ==
  
=== PRE_BUILD ===
+
== PRE_BUILD ==
 +
* Apply patches or '''sedit''' here.
 +
** Create a separate patch file and apply it with '''patch_it'''.
 +
** 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'''.
  
=== BUILD ===
+
== BUILD ==
  
=== POST_BUILD ===
+
* Try to avoid patching source files here. Place these patches in PRE_BUILD.
  
=== POST_INSTALL ===
+
* Don't install files after calling '''devoke_installwatch'''.
 +
** Try hard not to require '''devoke_installwatch''' at all. Don't use it, ever.
  
=== PRE_REMOVE ===
+
* Don't use ( ... ) > $C_FIFO 2>&1.
 +
** This is no longer required and new modules shouldn't use them.
 +
** Remove them when altering a module and remove the corresponding initial indent.
  
=== POST_REMOVE ===
+
== POST_BUILD ==
  
== Definition Of Good Style ==
+
* Don't install any files into the system.
 +
 
 +
== POST_INSTALL ==
 +
 
 +
* Don't install any files into the system.
 +
 
 +
== PRE_REMOVE ==
 +
 
 +
== POST_REMOVE ==

Latest revision as of 22:13, 9 June 2013

Contents


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 eert and 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.
  • Use lvu links to help determine depends.

CONFLICTS

  • Remember to add a CONFLICTS to both modules that conflict with each other.
    • Use lvu conflicts to help determine conflicts.
  • 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

  • Apply patches or sedit here.
    • Create a separate patch file and apply it with patch_it.
    • 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.

BUILD

  • Try to avoid patching source files here. Place these patches in PRE_BUILD.
  • Don't install files after calling devoke_installwatch.
    • Try hard not to require devoke_installwatch at all. Don't use it, ever.
  • Don't use ( ... ) > $C_FIFO 2>&1.
    • This is no longer required and new modules shouldn't use them.
    • Remove them when altering a module and remove the corresponding initial indent.

POST_BUILD

  • Don't install any files into the system.

POST_INSTALL

  • Don't install any files into the system.

PRE_REMOVE

POST_REMOVE

Personal tools
Namespaces
Variants
Actions
Wiki Navigation
Project Sites
Toolbox