1. Sulaiman Mustafa
  2. cript

Overview

HTTPS SSH
                                      CRIPT
                                  version 1.0.3
               drop-in self-building source-code executable packages
                               Sulaiman A. Mustafa
                        Sat, 2nd of Rabi' Al-Awwal, 1435
                                 


  ______________________/INTELLECTUAL PROPERTY NOTICE\________________________
 |                                                                            |
 | License/Copyright: See the file COPY in the base directory of this project |
 |____________________________________________________________________________|



DESCRIPTION
-----------
A Cript package is an executable source-code package that can be invoked as if
it was the source code's compiled result. This enables users to treat code that
would normally require additional steps to run as scripts. The compiling stage 
is done transparently, and is cached to speed up future invocations.

This project contains the software that generates cript packages.

CRIPT serves three goals:
    A.  To enable users to run compiled programs in the same way users would 
        run dynamic scripts.
    B.  Produce a self-contained executable unit. 
    C.  To be as transparent as possible.

Some positive consequence:
    A.  Free cross-architecture support
    B.  Custom-built binaries for the host system

How it works: cript packages are nothing more than bash scripts that contain 
source-code and instructions on how to build it. When a cript package is being 
generated, the source-code is compressed, encoded, and then embedded it the 
resulting script. From your users' perspectives, a CRIPT package is the binary 
itself with two key advantage, it runs immediately without compiling, and the
resulting binary is custom built for the host machine.

CRIPT IS NOT A BUILD SYSTEM AND SHOULD NOT BE TREATED AS SUCH. A CRIPT package 
is a bash script with an embedded tarball that automatically executes a build 
script when deemed necessary. A cript package does not check dependencies nor 
does it tend to distribution specific anomalies. If you target multiple 
platforms, the responsibility of handling each target lies entirely on your 
shoulders.

It goes without saying that there will be a delay when a package is executed 
for the first time, or when the cache is stale or unusable. This delay is 
caused any time a cript package rebuilds the cache. Depending on the amount of 
work required to build the binary, a rebuild could take a couple of 
microseconds or an hour or two.
 
A cache rebuild is triggered if a cache is not present or was generated by a 
different script or if a package is newer than its cache.



USAGE
-----
To embed source-code in a cript package, you need three things: A source 
directory, a build script, and a signature key. A source directory is the 
directory that contains all files necessary for a build. This directory will be 
compressed and embedded in the resulting script using tar and gnuzip. A build 
script (`build.sh' by default) is a bash script that builds the source code and 
produces an executable, and should be present in the source directory. Note 
that name of the executable produced MUST MATCH the name passed to cript, or 
the cript package will fail to execute.

If the build script fails (i.e. exits with an error code) or prints output to
stdout or stderr, the package will also fail. See the section entitled 
"BUILD SCRIPTS" for more information.

To generate a cript package, cript is run with its three requirements:

    source/cript SIGN_KEY_ID PATH/TO/SOURCE/DIRECTORY NAME



if no error occurs, a new file named NAME will be present in your current 
working directory. This is your packaged source code.

You should test it by invoking the package as you would invoke what the source 
compiles to:

    NAME ARGUMENTS

where ARGUMENTS are the arguments you would pass to the normal, compiled 
binary.



CRIPT PACKAGES
--------------
Cript packages are meant to be completely transparent, and users should be able 
to replace them with the compiled binary without issues should they choose to
do so. 

However, there are a few environment variable you could use to influence the
behavior of cript packages. 

Note: To set environment variables in bash, simply perpend them before the 
      command: VAR=VAL NAME ARGUMENTS


                     CRIPT ENVIRONMENT VARIABLES
 ---------------------------------------------------------------------------
  Environment variables cript understands:
  
      CRIPT_VERBOSE='yes'             Print extra information to tty. If 
                                      script is not attached to a tty, it 
                                      is written to 
                                            
                                        /tmp/USER.{NAME}.script.log
                                        
                                      if CRIPT_CACHE_DIR is not set, or 
                                          
                                        CRIPT_CACHE_DIR/USER.{NAME}.script.log
                                      
      CRIPT_CACHE_DIR='{PATH}'        Set {PATH} as cache directory 
                                      (default is /tmp). This can be used 
                                      give executables a more resistant 
                                      home.
      
      CRIPT_OP='EXTRACT'              Extract compressed source into the 
                                      current working directory and stop.
      
      CRIPT_OP='INFO'                 Print information about the cript 
                                      package itself.
                                      
 ---------------------------------------------------------------------------
    Any non-empty string is regarded as set, while an empty string is 
    regarded as unset.


BUILD SCRIPTS
-------------
Build scripts have two primary objectives: to build a project quietly, and to
produce an executable with the same name as the one passed to the CRIPT script.

There are a few rules need be followed when writing build scripts. some of 
these rules are semi-enforced, while other aren't. Regardless, these rules must
be followed or the package looses transparency. These rules are:

    1.  Build scripts must never modify anything other than the directory they
        are executed in or subdirectories.
    2.  Build scripts must never send anything to stdout or stderr unless on 
        fatal errors and when absolutely necessary. You can send output to 
        /dev/tty (if attached to a tty) which should not effect the process's 
        output streams, but doing so is not recommended because it would detract 
        from the transparency of the package.

If the script is unable to build the executable, it should print errors to 
stderr or stdout.

A non-zero exit code is taken as an indicator of failure, and will cause the 
package to fail.



Example
-------
Included in the CRIPT distribution is a minimal working example of a source 
directory and a build script. To produce a cript package, run the following 
command in the base of the CRIPT distribution directory:

    source/cript username example.d example

The resulting executable `example' is the generated package.
    


Support and Help
----------------
While I can't promise prompt responses and 24/7 hotlines, I'll try my best to 
reply in a timely fashion. If I don't reply to email, it might be because I 
switched to another provider again. Try other communication channels such as the
issue tracker (PLEASE include your email with the bug report so that I can get 
back to you if I need more information).



Contact Information
-------------------
Personal: http://seininn.bitbucket.org/contact
Issue tracker: http://bitbucket.org/seininn/cript/issues/new