Current extension guidelines.

[Jason W]

The purpose of this post is to keep an updated set of extension guidelines
available in one place.  I will try to place all the needed information here.
Please post any comments or questions in the other guidelines thread.  

#############

When a Tinycore extension is made, the extension submitter is the maintainer
of that extension.  If there is a desire for the extension to be updated, or if there
is a bug in the extension, it can be mentioned in the TCE Bugs thread or in the
extensions announcement thread.  If one wants to update or fix an extension that is
maintained by someone else, it is expected that the extension maintainer be contacted to be sure that it is agreeable.  If the original extension maintainer is no longer active or cannot be reached, then after a period of time (I would say about a week or so) then one can commence with the fix or update.  I
will have to assume that when an update to an extension is submitted that the maintainer has
been contacted and is ok with it as it would simply be too much of a time demand for me to act as a liaison in each case.  The extension area thrives on collaboration and pulling together, but communication among extension maintainers is vital.

#############

Extensions should be applications or libraries preferably compiled on
Tinycore Linux.  Refer to the wiki for TC building policy.  Binaries of
applications from the author's website are acceptable especially in the
case of things like web browsers that are a
tedious build and the official build is known to run well.  However,
repackaging apps or libs from another distro is discouraged as a general
practice.  Custon scripted utilities, like update, install, uninstall funcions belong
in the "programming and scripting" section of the forum.  Well known scripts like
bashburn and python packages are ok.

##############

Build extensions to install into /usr/local whenever possible.  When this
is the case, include "This extension is PPI compatible" in the info file
of tce extensins.  Refer to the kernel module extension thread for kernel
modules installed into /usr/local.

#############

Make sure that the permissions of /usr/local/tce.installed are set to owner root:staff and
775 perms.  This and other things are checked when using the extension audit script so using the
script to check extensions before submitting is helpful.


#############

Whenever possible, try to preserve the upstream package name instead of making up a more descriptive name for your extension.  Exceptions, of course, are things like base-dev, Xlibs_support, and others that are several sources packed into one for a special purpose.  But those are by far the exception and not the rule.  
If the upstream source name is fox-1.2.32.tar.gz, then the extension name should be fox.tczl, fox-dev.tcz, fox-lib.tczl, or whatever it gets split into.  If there is a 2.x version of fox as well as a 1.x version, then the two packages would be named fox1.tczl and fox2.tczl accordingly.  As mentioned elsewhere, the actual version numbers should stay out of the name though.  But strive to keep the extension name as true to the upstream package as possible.  If I were to make an extension of epdfview, the gtk2 pdf reader, I shouldn't name it gtk2-pdf-viewer, or gtk2-pdf even though those names may seem more descriptive.  Description belongs in the info file, package names should stay true as possible to the upstream source.

#############

Please do not include the version number in the names of extensions.  Doing so means a change
in the name of the extension on each update.  If the name of an extension changes, all extensions that
depend on that one have to have their dep files adjusted.  Also, a name change in an extension causes an error when tce-update is run.  If the dep files in user's existing tce directories are not changed when an extension name is changed, there can be errors booting when the old extension is removed and the newer one put in it's place if the name has changed.

So it helps everyone to leave version numbers out of the names of extensions.  There are times that including the version is necessary to avoid issues, like with the kernel module extensions or openssl, but only then should version numbers be used in the name.

#############


Use the squashfs-tools to create tcz extensions.  The basic command for making a tcz is this if your extension is installed in a directory called "pkg":

mksqashfs pkg/ extensionname.tcz

If not using the most current squashfs-tools extension, use this command to make sure
that you are using 4096 block size.  ALL EXTENSIONS HAVE TO BE 4096 BLOCK SIZE
OR THEY WILL NOT WORK:

mksqashfs pkg/ extensionname.tcz -b 4096


################

When making development, locale, doc, or other types of extensions, be sure not to use
plural in the extension name.  In other words, name them like this:

extension-dev.tcz   extension-doc.tcz  extension-locale.tcz  extension-lib.tcz

If they are named -docs, -devs, -locales, -libs, etc the extension will be turned away.

#################

Send extensions to tcesubmit _at_ gmail _dot_ com.  It may be necessary
to send the files in two or more different emails depending on the size
of the extension files.  If you submit an extension and a week goes by without
a response or posting let me know.

##############

Extensions need to have a license that allows redistribution in binary
form.  If you are not sure, you can ask in the forum.  

Also, freeware that requires a registration key is not allowed, even if the license allows redistribution.

Please send in build instructions and a link to the source with each extension.

##############

Remember to strip libraries and binaries as that greatly reduces size.  "strip -g" for shared objects and "strip --strip-unneeded" for executable binaries.  These two commands issued in the directory where the extension was installed makes easy work of this:

Code: [Select]

find . | xargs file | grep "executable" | grep ELF | grep "not stripped" | cut -f 1 -d : | xargs strip --strip-unneeded 2> /dev/null
find . | xargs file | grep "shared object" | grep ELF | grep "not stripped" | cut -f 1 -d : | xargs strip -g 2> /dev/null


############

Extensions need these basic files:

extension.tcz.dep   #The list of dependencies, this is only needed if there are
           dependencies that the extension needs.
extension.tcz.info   # The info file.  Look at those in the repo for examples.
extension.tcz.list   # The file list.  Made like this:

Code: [Select]


For .tcz:

mkdir pkg
mount -o loop extension.tcz pkg
cd pkg
find `ls` -not -type d  > /tmp/extension.tcz.list


extension.tcz.md5.txt  # the md5sum.

##############

Please send in the extension files in a tarball encrypted with bcrypt.  This
will help keep them from being caught in the spam trap.  The command is this:

bcrypt extensionfiles.tar.gz

and the password to use is "tinycore".

##############

Please do not include the version number in the name of library extensions.  That
causes every app's dep file that depends on that lib to be updated whenever the library
extension is updated.  End usage apps are not so important, but with library extensions
this is very important.

PLEASE DO NOT INCLUDE VERSION NUMBERS IN THE NAME OF LIBRARY EXTENSIONS THAT OTHER
APPS WILL USE OR THE EXTENSION WILL BE TURNED AWAY.  This is essential as otherwise an update
to that extension will break the dep files of any that depend on it.  

##############

It is preferable to seperate out development files and locale files as they take up space.
This is somewhat left to preference, and if you are not sure how to seperate the extension
into a -dev one then it would be better to leave it in one piece.

##############

Please write a descriptive and concise entry in the Description field of the info file.
Also remember to include the "TESTING" label beside the description field.

##############

Use this format for the date field:  YYYY/MM/DD
For instance 2009/01/01 for Jan. 1 2009.  Any variation on this format
will not display properly on the web page

#############

Use the startup script to copy or create files in the $HOME directory if needed.  /etc/sysconfig/tcuser contains the proper TC user, and it is valid both during boot and runtime.  Example startup script to create file in $HOME directory:

Code: [Select]

#!/bin/sh

TCUSER=`cat /etc/sysconfig/tcuser`

[ -d /home/"$TCUSER"/.mplayer ] || mkdir /home/"$TCUSER"/.mplayer

[ -f /home/"$TCUSER"/.mplayer/subfont.ttf ] || ln -s /usr/share/fonts/luxisr.ttf /home/"$TCUSER"/.mplayer/subfont.ttf

chown -R tc:staff /home/"$TCUSER"/.mplayer


Note:  It is very important to set the permissions on the startup script to root:staff/775.  The same for the /usr/local/tce.installed directory itself.  This directory needs to be read/write/execute for group staff.

##############


Do not use a text editor that creates CRLF line terminators to make the info file.  In other words, do
not edit or create your info file on a Windows machine.

##############

I am sure I have missed something, but I will keep this post current for easy reference.   

##############

Oh, and this is last but definitely not least.  You guys are doing a great job.  Thanks, and keep up the good work.