Creating Extensions

Creating an Extension

• Creating an Extension
  • 1. Related Topics
    • 1.1. Required info
    • 1.2. Abbreviated steps
  • 2. Installing
  • 3. Creating a .tcz
  • 4. When DESTDIR Fails
  • 5. Adding Custom Startup Scripts
  • 6. Name Variations Deprecated
  • 7. Testing
  • 8. Submission
    • 8.1. Separation
    • 8.2. Required Files
    • 8.3. Send to

This article assumes the user is comfortable at the command line. Using these instructions, the user will:

• create temporary files and directories
• output the final files to a temp directory
• use make and squash file tools

Required:

• Your source code and all dependencies
• compiletc extension
• squash file tools extension

1. Related Topics

1.1. Required info

• The package maintainers (JW in particular) use the forum to post the most recent extension creation guidelines. You need to read the recent guidelines forum thread and the FAQ entry for submission
• For information on creating icons, menu entries, setup scripts, .info and .dep files, please see iconmenuinfo.
• Packaging kernel modules: thread.
• Tiny Core v2.4+ uses extensions in .tcz format. Other formats are deprecated.
• Tiny Core v2.7+ only uses the .tcz extension. There are no filename extension variants. If you don't know what that means ... be thankful. Just create files ending in tcz.

1.2. Abbreviated steps

The Six Big Steps:

• configure/make/make install
• separate out docs, locale info, and development files
• squash up everything into your extension(s)
• write & place support files: dep, info, list, and md5 hash
• bcrypt/tar it all
• email it to the Tiny Core Team

Much can be scripted and the payoff is well worth it.

2. Installing

Use the compiletc extension when compiling your source - it includes the most common tools, all set up for tc (gcc, make, etc). If you are getting strange make errors, try the coreutils extension. Tar errors? Get the tar extension. And so on.

Please note that the standard install prefix for TC is /usr/local

Suggested compiler flags (for compatibility):

export CFLAGS="-march=i486 -mtune=i686 -Os -pipe"
export CXXFLAGS="-march=i486 -mtune=i686 -Os -pipe"
export LDFLAGS="-Wl,-O1"

If you wish to try to get a lower sized C++ app, you can try adding "-fno-exceptions -fno-rtti" to CXXFLAGS. Use only on C++ applications, libraries should use the same flags as in CFLAGS above.

Flags Not-allowed (good performance, but likely won't work on other machines):

Please refer to http://www.gentoo.org/doc/en/gcc-optimization.xml and http://gcc.gnu.org/onlinedocs/gcc-2.95.3/gcc_2.html for more compiler flags info.

Setting pkg-config paths via export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:/usr/lib/pkgconfig is no longer required as the default in the latest extension includes /usr/{local,}/{lib,share}/pkgconfig.

Example steps to configure and compile a package_name.tar.bz2:

tar xjvf package_name.tar.bz2
cd package_name
./configure --prefix=/usr/local
make -j3

Note: -j3 is meant for a 2 processor system. The general guideline is -jN where N is 1 more than the total number of processors available.

Create/update a date marker just in case your app doesn't support DESTDIR:

touch /tmp/mark

Install the application:

make DESTDIR=/tmp/package install

(see below, "When DESTDIR Fails" if needed.)

Note: some packages support make install-strip, which strips off debugging information. Jason W recommends doing so to save space. He also mentions that you can do it post-make with:

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

Run these on your package directory tree before you tar it up. Busybox xargs does not support the file argument, so it will bail. You need to keep the compiletc extension loaded for the full xargs version.

3. Creating a .tcz

If the program supports DESTDIR (most do) the files will be installed in /tmp/package, but configured for /usr/local. In this case, create extension like this:

cd /tmp
mksquashfs package program_name.tcz
cd /tmp/package

Next create the list of files in the extension, it will be submitted with the extension:

find usr -not -type d > program_name.tcz.list

As a final step, remove the packed files from /tmp/package:

rm -rf usr

4. When DESTDIR Fails

Just about all applications support the use of DESTDIR on the make line (as above). There are those that don't, however. If your application does not support DESTDIR, it will likely install into subdirectories of root, rather than tmp.

One possible solution from the forums, by Jason W, uses a time stamp, find, and tar.

As above, set the ./configure installation prefix as normal. Then be sure to create a time stamp after make, but do it just before make install. Use find to list all the newly installed files, and then gather those files up using tar.

./configure --prefix=/usr/local
make
touch /tmp/mark #in case DESTDIR fails
make install DESTDIR=/tmp/pkg #DESTDIR may not work ...
find /usr/local -newer /tmp/mark -not -type d > /tmp/list
tar -T /tmp/list -czvf /tmp/someapp.tar.gz

For TC past 2.4, you will need to unzip the tar file, and then use mksquashfs to create your extension:

mkdir /tmp/pkg
cd /tmp/pkg
tar -xf /tmp/someapp.tar.gz #'install' the extension in tmp
cd /tmp
mksquashfs pkg/ someapp.tcz

Be careful using touch/find -newer method. There are files just copied by installer from the source package, like configuration files, header files, scripts, doc files, images, etc. with original date, therefore they are not detected. Check installer messages!

5. Adding Custom Startup Scripts

Create a shell script /tmp/package/usr/local/tce.installed/package_name if you would like to do something when the package is 1st installed or again mounted on boot.

A good pattern to follow would be to first rename /tmp/package/usr/local/etc/package_name.conf to package_name.conf.sample, and for your script to check always whether /usr/local/etc/package_name.conf exists, and if no, copy over /usr/local/etc/package_name.conf.sample into it. This is so that the application's configuration files are fully writable in the natural path, without having to resort to weird paths that you determine on your own.

e.g.

cd /usr/local/etc/
[ ! -e nano.rc ] && cp -p nano.rcsample nano.rc

Warning: If you don't do this now, these configuration files would be read-only.

Please read iconmenuinfo wiki page for more information on creating wbar icons, menu entries, setup scripts, .info and .dep files.

Important step before you move on:

chown -R root:staff /tmp/package/usr/local/tce.installed
chmod -R 775 /tmp/package/usr/local/tce.installed

6. Name Variations Deprecated

In short, Tiny Core 2.7 and after only use extensions (1) ending in tcz and (2) created using squashfs.

The forum records some of the reasons why, and how it came about.

If you're dying to know, TC 2.4 to 2.6 used a single letter suffix added to tcz:

• .tcz - standard extension
• .tczl - extension with libraries
• .tczm - extension with kernel modules

Use of proper name was necessary to for execution of 'ldconfig' (.tczl) or 'insmod' (.tczm) when loading extensions. Before 2.4, tce was also used. In any case, these are all deprecated.

If you find yourself creating extensions for older TC versions, be aware that they (1) will require the correct file names and (2) they may not port nicely to TC 2.7+.

7. Testing

Test out your new extension(s) by manually loading them after booting TC with the cheatcodes:

Load your extension, and check: (1) all dependencies loaded? (2) menu item works? wbar/desktop icons work? (3) program actually runs?

It is easy to leave out a required dependency from your .dep file. Do use base norestore, and check the dependencies in particular.

8. Submission

8.1. Separation

Smaller extensions reduce 'bloat' in Tiny Core. To help out:

• move translations and other locale data into a locale extension (myprogram-locale.tcz)
• move documentation and help files into a doc extension (myprogram-doc.tcz)
• rather than including docs in your extension, use the info file to list official online docs.

8.2. Required Files

Submissions must include:

• The extension file (.tcz)
• a list of its contents (.tcz.list)
• an md5 sum (.tcz.md5.txt)
• an info file describing its contents (.tcz.info) - this content is standardized. Visit the repository for examples.
• a dependency list, if necessary (.tcz.dep)

8.3. Send to

Submissions are emailed in according to the most recent submission guidelines (read up at the recent guildelines forum thread).

---