Module Guidelines
From Lunar Linux
(Difference between revisions)
(→DEPENDS) |
|||
| (7 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
| − | + | __TOC__ | |
== Generic == | == Generic == | ||
| Line 10: | Line 10: | ||
* Always use a SHA1 checksum instead of a MD5 checksum for SOURCE_VFY values. | * 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. | + | **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. | * 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. | * 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. | * Avoid using the module's name in the SHORT field. | ||
| − | ** e.g. instead of <code>SHORT=" | + | ** 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 | + | ** 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. | * 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. | * 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 == | == DEPENDS == | ||
| Line 23: | Line 28: | ||
** 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." | ** 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]]. | * 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 | + | ** 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. | * 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. | ** 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 ' | + | * 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 == | ||
Latest revision as of 23: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 useSHORT="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.
- e.g. instead of
- 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.
