
About this Program
==================

CreateSEC
Copyright  2010, 7th software
All rights reserved.

CreateSEC is a tool for creating "self-extracting code". The idea is that
files, directories and applications can be compressed into a single file (an
executable program) which when run will decompress itself without needing any
extra programs to be available (such as dearchiving applications).

The CreateSEC tool requires !Routines 1.40 or later, which can be downloaded
from http://www.7thsoftware.com/.


Using the Graphical User Interface
==================================

Simply double-click !CreateSEC and it will load onto the iconbar.
Select-click the iconbar icon to open the main window. Drag the file,
application or directory that you want to compress to the "Input" writable
icon.

To specify the output file, you can either type the name into the "Output"
writable icon, or you can drag a directory there and then add a suitable
leafname. Do not just drag an output directory there because you risk it
being replaced by the output file (if you specified "Force")!

Clicking on "Run" will start the compression process.

If you select the "Verbose" option, the tool will output verbose status
information about the compression operation.

If you select the "Force" option, the tool will delete any object found to
match the name entered in "Output" before creating the output file with that
name. This is intended to be used to force the replacement of a previously
generated output file.

Selecting the "No code" option will cause the output to be created _without_
the self-extraction code; just the raw compressed data is output. This is
only useful if you intend to use it with a third-party decompression tool.


Some points to note:

- You are not allowed to specify the same object for both the "Input" and
  "Output" - this would require wiping the input object before the output
  object can be created!

- You can create output objects with the same leafname as the input object
  but this has side-effects:

  + For a file, the self-extracting code file will be replaced by the
    decompressed version when it is run

  + For a directory, attempting to run the self-extracting code file will
    result in an error (because a directory cannot be created in a location
    where there is already a file of the same name).

  Both of these issues are not a problem if the user specifies an alternative
  location to decompress the file to (see below) but in the general case,
  this should not be relied upon. It is suggested you append the string
  "util" (or similar) onto the output filename.


Using the Command Line
======================

Self-extracting code can be created as above, but using only the command
line.This way is simpler in situations where you do not have a complete
!System installed (because the GUI front end for CreateSEC requires some
modules which you may not have access to). However, it still requires
!Routines to have been 'seen' by the Filer.

- Simply ensure that the Filer has 'seen' the !CreateSEC application - if you
  are reading this !Help file, then it almost certainly has already!

- Press ctrl-F12 to open a task window (or just F12 to drop to the shell)

- Type this command (followed by 'return'):

  *CreateSEC <input> <output>

  where <input> is the name of the file, application or directory that you
  want to compress.

  and <output> is the name of the self-extracting code file that you want to
  create. For example, you could just do:

  *CreateSEC $.!MyApp $.MyApp/util

  You can use the -v switch to enable useful verbose output.

  The -f switch can be added to cause any pre-existing output object to be
  wiped. USE WITH CAUTION!

  Add the -n switch to build a data-only archive (without the self-extraction
  code).

  Add the -d switch to include debugging information in the archive, that
  will be output when the archive is extracted. This is probably only useful
  to those who want to debug this program.

- If you dropped to the shell, press return a couple of times to return to
  the desktop


How to Decompress the Output File
=================================

The simple way to decompress the self-extracting code file is to first ensure
it has the correct filetype. It should be type "Utility" (&FFC). This can be
checked and set from the Filer menu or command line.

Next, simply double-click the file to run it. An hourglass may appear as the
decompression process is underway. When complete, the decompressed contents
of the file will have been placed into the same directory as the file you
ran.

You can also decompress these files from the command line simply by running
them in the normal way. If you pass a directory as a parameter (the first and
only parameter) to the file, it will decompress into that location rather
than the same directory as itself.


Squashed Data File Format
=========================

The data appended onto the end of the self-extracting program is stored in
the ROOL Squash data format ("rsqs"). This has been designed specifically to
make it simple to both create and decompress these data structures, which are
able to hold information about RISC OS files and directories.

As the self-extracting code is implemented as a transient utility, the format
of the code will look like the following:

  0..23 RISCOS Ltd 32-bit header
  24    Offset to start of the compressed data structure (described below)
  28..  ARM code for the self-extraction routine

Note that the word at offset 24 can be used by 3rd party extractor tools to
locate the start of the compressed data and skip over the self-extraction
code which is probably of no interest.

In a little more detail, the 32-bit header looks like this:

  0     Branch instruction to start of ARM code
  4     &79766748 = "Hgvy"  }
  8     &216C6776 = "vgl!"  } these two words are ROT13("Utility!")
  12    total size of utility and data (bytes)
  16    0
  20    32

The appended data is stored in the following format (note: the size of this
data is included in the calculation of the total size of the utility):

  one (header block, must be at start of data)
  zero or more of either:
    filename block followed by filedata block
  or:
    filename block followed by dirdata block

HEADER BLOCK

  0     "rsqs"
  4     offset to next block (bytes from byte following this word)
  8..   zero or more extension words (undefined bits should be zero)

FILENAME BLOCK

  0     "rnam"
  4     offset to end of block (bytes from byte following this word)
  8     file name (zero terminated, pad with zeros to word boundary)
  n..   zero or more extension words (undefined bits should be zero)

FILEDATA BLOCK

  0     "rdat"
  4     offset to end of block (bytes from byte following this word)
  8     load address
  12    exec address
  16    attributes
  20    squashed data size (bytes)
  24    uncompressed data size (bytes)
  28..  data (pad with zeros to word boundary)

DIRDATA BLOCK

  0     "rdir"
  4     offset to end of block (bytes from byte following this word)
  8     attributes
  12    zero or more extension words (undefined bits should be zero)

File format notes:

- Directories must be defined before the files within are defined.

- Unknown block types or out of order blocks are ignored.

- Assumes 32 bit, little endian word


License
=======

Copyright (c) 2010, 7th software. All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

- Redistributions of source code must retain the above copyright
  notice, this list of conditions and the following disclaimer.

- Redistributions in binary form must reproduce the above copyright
  notice, this list of conditions and the following disclaimer in the
  documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE HORDE PROJECT OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING  NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE
