Kallist's Trove

Download KTrove

KTrove lets you keep Zaurus programs on a memory card, even if you can't install them there in the first place.  Download the package and install it on your Zaurus internal memory as normal.  Read the help file you'll find in your Documents tab (also reproduced below for convenience) for more information.

Questions or suggestions?

Kallisti Trove 1.0
 

For All Your Removeable Card Needs. Sort Of.
A Fine Service of The Barry BitTwister Cabal.
Hail Eris.
 

READ THE "WARNING" SECTION BELOW

 Now that we've got that over with, be sure to read the rest of this as well. Or better.

Contents

WARNING
REQUIREMENTS
THEORY OF OPERATION
HOW TO USE THIS BLASTED THING
    COMMAND LINE OPERATION
    GUI OPERATION
EXPERT ISSUES
    Customizing the File List
    Manual Repairs
SUPPORT
 
 

KTrove (for short) grew from the Z's oppressive limitations regarding where programs get installed and used. Oh, sure, you can TRY and pick something other than RAM. Something innocuous like "CF", or maybe get a little wild and go all the way for "SD". But, more often than not, you've simply been fooled, crushed under the bootheels of incompatibility and told to simply fark off.

Well, no more. This little gem of a proglet will solve all your problems, and end suffering for all of mankind and bring peace and joy to the land. Or it could mess you up bigtime, so don't skip reading the rest of this README. DON'T! I promise I'll try to make it funny.

WARNING

Here's the quickie warning for those of you who won't read the README. I know, you're not reading this for said reason, but at least this way I can point at you and laugh when you've made a mess of things, because I TOLD YOU SO.

Here's the warning: This software works by unabashedly lying to your Z. It's unethical, and as always, a little risky. Specifically:

DO NOT UNINSTALL OR UPGRADE APPLICATION PACKAGES THAT ARE BEING MANAGED BY KTROVE. All you gotta do is unregister the app from ktrove first, then nobody has to get hurt. Just don't forget.

REQUIREMENTS

A Zaurus 5500 or equivalent
Optionally, but recommended: Opie-SH

THEORY OF OPERATION

Our trained experts at the BBC (no relation) have learned to synthesize a substance known to the layperson as "magic pixie dust". The actual process is secret (although now involves less suffering by pixies then it used to), so I can't really tell you any more about that. Instead, here's our cover story.

As it turns out, most applications for the Z can be run from somewhere other than where they live through the use of this pix... I mean, "symbolic links"

KTrove takes advantage of this by pulling the wool over the eyes of the Z and copying all of the files that go with a given program somewhere else. Say... to your compact flash or SD. It then provides an easy mechanism to create and delete the set of symbolic links to make it look like these files are actually in your main memory. Except they aren't, so you don't use up (much) main memory.

Note: some applications won't actually work properly this way (although almost all do. I use this to keep an entire web server (apache + mysql) on an SD card)

Also, this bit about lying to the Z about where it's brains are can lead to a problem: If you are in the middle of pulling off this fraud, and you decide to do something like uninstall or update the application that isn't really there, things can get mightily confused. DO NOT UNINSTALL OR UPDATE APPLICATIONS BEING MANAGED BY KTROVE! UNREGISTER THEM FIRST!

HOW TO USE THIS BLASTED THING

Here's the general idea:

1. Install the application you want to manage as normal, on internal RAM. You might want to run it, just to be sure it works.
2. Register the application with KTrove. This moves the application's files to the trove location, and out of your internal RAM.
3. Before you use the application, use KTrove to activate it. This sets up the required linkage so your application will run.
4. You can leave applications activated without using much internal RAM.
5. When you want to remove the card containing the trove, deactivate the applications on the card first. This removes the linkages, and makes the application "disappear". The card can now be removed.
6. If you want to put the application back into your internal RAM, then unregister the application from KTrove. The files will be moved back, and you can uninstall, update, or do whatever you like with them as normal.

NOTE: If, after you register & activate a program, you find it doesn't work right - simply unactivate and unregister it. All should be well, but KTrove won't handle your program. Maybe. If you're brave, check the "Experts" section below for ways you can jigger it to work.

Here's the specifics:

There are two ways of using KTrove - command line and gui, using Opie-Sh. We at the BBC strongly recommend using the gui! The gui is started by tapping on the KTrove icon that was installed with the package. If you don't have Opie-SH installed, then the installed icon usefully functions as a local version of TRBBTDDA.

Command Line Operation

For you techno-macho dudes who don't use guis, I'll describe the command line first. Type this at the command line, and you'll see a quick command summary:

    ktrove.sh -h

The summary will look something like this:

  /opt/QtPalmtop/bin/ktrove.sh [options]
  A product of the BBC (no relation)
  THIS PROGRAM CAN MESS YOU UP.
  READ THE README.

  [options] is one or more of:
  -a <pgm>  Activate Program
  -c <pgm>  Check Program Status
  -d <pgm>  Deactivate Program
  -g        Use Opie-Sh GUI
  -h        This help message
  -l        List Available Packages
  -r <pgm>  Manage this Program
  -s        Gets the status of the trove.
  -t <path> Use A Trove at <path>
  -u <pgm>  Stop managing this program
  -v        be verbose

If you've read the general idea up earlier, you can probably figure things out from that. Here's a blow-by-blow anyhow, in the order you're likely to want to use the commands.
 

-t    Sets the trove.

This options does nothing by itself, but affects the operation of options that follow it on the command line. The options it affects are: -a -c -d -r -s -u

By default, all of those options assume that the trove you want to mess with is "/mnt/card". Use -t to change this assumption. You can specify any location you like with -t. These are the paths you might like to use:

    /mnt/card       This is the SD Card
    /mnt/cf         This is the Compact Flash card
    /home/root      This is internal RAM

usage example: ktrove.sh -t /mnt/cf -s

-v    Sets verbose mode.

This makes KTrove tell you what it's doing while it does it. It only affects operations that follow it on the command line. Maybe you like this kind of thing, but the messages are voluminous, so you probably just want to never use it.

usage example: ktrove.sh -v -r <program name>

-l    Lists Available Programs.

Shows you a list of all the programs you have installed on your Z. Whenever KTrove wants a "program name" it means that it wants a name from this list.

Usage: ktrove.sh -l

-s    Gets the Trove Status.

Shows you a list of all the programs that the specified trove is managing, as well as whether they are currently active or not.

Usage: ktrove.sh -s

-r    Registers a program with the trove.

Use this to move a program to the trove and begin management. Once registered, the program is not available for use. You have to activate it first.

Usage: ktrove.sh -r <program name>

-a    Activates a registered program.

Makes the program available for use. As a fun little gimmick, you can specify the special program name "-ALL-" to make KTrove activate all the programs registered with the trove at once.

Usage: ktrove.sh -a <program name>
Usage: ktrove.sh -a -ALL-

-d    Deactivates a registered program.

Makes the program unavailable for use, probably in anticipation of unmounting a card or unregistering the program. You can use the special "-ALL-" filename here, too, to deactivate everything all at once.

usage: ktrove.sh -d <program name>

-u    Unregisters a registered program

Moves the program back into the location it was in before KTrove messed with it in the first place. Do this before uninstalling or updating a program.

usage: ktrove.sh -u <program name>

-c    Check Program Status.

This is really meant for use when running ktrove from other scripts. You can pass it a program name, and it will return a "0" if the program is not activated, and a "1" if it is.

usage: ktrove.sh -c <program name>

-g    Runs the program under the Opie-SH gui.

usage: ktrove.sh -g

That's about it!
 
 

GUI Operation

This is a much easier way to use KTrove, since you'll be guided through the data collection visually. Because this is based on Opie-Sh, and because the programmers here at the BBC like to do weird things, this gui has a little bit of a personality. So, keep in mind two things:

1. It's a bit slow. Have patience.
2. During normal operation, KTrove will look for all the world like it closed down. It didn't, unless it disappears for longer than a second or so. In that case, something crashed, and you should tell us about it.

Start the gui by either tapping on the KTrove icon or by entering "ktrove.sh -g" at the command line.

You'll be presented with a screen that tells you what your current trove is, provides you with a little pull-down box. This box is your little friend, and is with you always. You can drag it around to get it out of the way of text you want to read.

The pulldown provides a list of commands that echo the command line parameters described above, so I'm not going to rehash what they each do here. You figure it out.

Oh, and you can always tap the little "x" on the command box to abort whatever process you accidentally initiated.

Expert Issues

Customizing the file list

When moving files to the trove, KTrove does not move anything in the /lib or /usr/lib directories, so as to avoid problems with removing libraries that might be needed by non-managed programs. Aside from these exceptions, KTrove manages all the files listed in the ipkg's file list. Also, by default, it only manages specific files, not entire subdirectories.

You might not want this, exactly.

Sometimes, you might wish that KTrove leave alone a specific file, or conversely, you might want to add additional files or entire subdirectories to the trove that weren't part of the original package list.

This can be handy if there's a specific file that won't work when KTroved, but you want to KTrove the rest of the files, or if you want data directories to be KTroved along with the application.

There is no user interface to do these things yet. Until then, you can edit the control file yourself. Here's what to do. Register the program with KTrove, but leave it inactive (deactivate it if you have activated it).

KTrove makes a subdirectory in the "Trove Directory" (/mnt/card by default), called "kmnt". In there, you'll find a subdirectory named the same as your program, and a file called <yourprogramname>.kctl

To Add Files:

If you want to add additional files to the trove, create a directory path in the <program> directory that matches where the additional file(s) will live when activated. Move (don't copy) the files into the directory you just made, then add a line into the <yourprogramname>.kctl file that gives the (activated) path & file name. The "file" can be an entire subdirectory.

For instance, I have apache-1.3.19-php-4.0.5 KTroved on my SD card, but KTrove by default does not keep track of my actual website! To fix this, I located the directory "/mnt/card/kmnt/apache-1.3.19-php-4.0.5". By default, apache wants the website to live in "/home/www/htdocs", so I create that path in the trove:

mkdir /mnt/card/kmnt/apache-1.3.19-php-4.0.5/home/www/htdocs

And copy my website into the new directory. Then, I edit the file "/mnt/card/kmnt/apache-1.3.19-php-4.0.5.kctl" and add the line:
 

/home/www/htdocs

to the end of it. That's it! Now, when you activate apache, a link will also be created to point apache to the website. Since the directory itself is linked in this case, you don't need to add anything from inside the htdocs directory.

A side effect of this comes around when you unregister the package. During unregistration, all of the files that go with the application get moved back into internal memory. After this mod, that will include the entire website as well. If you have enough memeory available, no problem. If not, it will fail.

To ignore files:

It's just the reverse of adding. How'd you guess? Follow the same rules, but this time, move the files you want to ignore back to the place they are supposed to live, rather than in the trove. Then delete the reference to them in the kctl file.

Manual Repairs

It shouldn't happen to someone as awesome as you, but it is just possible that something could go horribly awry. If this happens, you probably aren't as screwed as you might think -- you just need to do a manual reset. You can get everything back to its normal (pre-registration) state by hand, like this:

Locate the .kctl file (described in the above section on adding and removing files) and use it as your guide.

Go through the list in the .kctl and make sure there aren't any stray symlinks left in the directories specified. If things went wrong after the program had been made active, but before it had been deactivated, there will probably be some. Delete them all, (but be sure they are actually links, and not actually files).

Now, move all of the files in the trove directory for your program (again, see above) back to their righful place. delete the subdir tree for the program in the trove, and also delete the .kctl file. In addition, there may be a hidden file with the .kctl file called ".<program>.activated". If this exists, delete it, too.

This should put everything back like it was before you registered the application.

Support

Didn't you read the disclaimers???

No support is offered or should be expected. That said, if you were to send email to us, you might get blessed with a useful reply of some sort. Suggestions are always welcome, too. Not as welcome as $100 bills, but we'll deal with it.