FELT for Command Line Hackers

This mode of installation is for projects that are intended to be run from "the command line" or as part of some other build process, for example as part of a Makefile, XCode stage or Eclipse build step.

In other words, FELT is being used in an "embedded" mode where it may or may not be forming the complete project at hand.

Get the code

Create a directory on your filesystem somewhere. For the purposes of this example I am going to call it "myfeltproject" and sit it in my home folder. So, open a command line console and enter these commands:

cd ~
mkdir myfeltproject
cd myfelproject
svn checkout http://felt.googlecode.com/svn/trunk/ felt-read-only

Wiring it up

In the felt-read-only/src/toolbox folder is a file called felt.php. This is the command line tool that you will use to get your FELT source code translated into some other output language. It is written in PHP but uses the #! operator to look and smell like a normal command line tool.

*nix Systems

If you are on a *nix system, Ubuntu in my case, then the simplest thing to do is to create a "soft-link" (symbolic link) between the file "felt.php" and one called "felt", which you can do by following these steps:

$ cd felt-read-only/src/toolbox
$ sudo ln -s /full/path/to/myfeltproject/felt-read-only/src/toolbox/felt.php /usr/local/bin/felt

What this does it makes a connection between the file in our checked out folder to one at /usr/local/bin/felt so, assuming that /usr/local/bin is in your $PATH variable, you now have the ability to execute FELT from anywhere on your machine.

You will of course be prompted to enter the root password for your system because the sudo command is being invoked to complete the last step. Once you have done this, if you type felt at the command line now you should be greeted with this output:

Usage: felt [options] [source-file-path]
Options:
 -sc / --syn_check        run the rendered code through a syntax check

 -cw / --code_wrap        wrap output in back-end specific sequences

 -o  / --output filename  save output to filename instead of stdout, if
                          multiple files are given they will be appended together.

 -as / --as-coder class   Use PHP class 'Class' to generate the target code, the
                          default language is PHP (PHPCoder). Write one!

 -err / --errormode mode  Use one of: console or json
 -p / --packed            Verbatim output, do not use \n between files in case that
                          might upset your custom rendering / generation process.

Please see the "FELT man page" for complete information on these options and how to use them.

Windows Systems

I don't have the capability to support Windows as I don't use it either personally or professionally so I can't do much here other than offer some basic advice on getting it set up on Windows.

On the official PHP site there is this page:

http://php.net/manual/en/install.windows.commandline.php

I highly recommend you read it before continuing.

Once you have managed to be able to type "php.exe" and have it run, it should be but a small step to create a .BAT file that can wrap that up and pass through the command line arguments.

I will attempt to create a working Windows 7 solution and post that as soon as I can.

Making sure it works.

If you have followed the instructions and nothing went wrong, then as a final test of your installation you can create a file called "test.felt" and put this single line of code in it:

(emit "Hello, world!\n")

I will assume that you have saved it in /tmp/test.felt or C:\TMP or something if you are on Windows. Whatever, just remember to specify the correct location of your file in the following, this will convert it into PHP without the tags which is the default operation:

$ felt test.felt
echo "Hello, world!\n";

$ # we'll do it again but ask for it to be wrapped in tags...
$ felt -cw test.felt

$ # and as proof, we will wrap it and run it!
$ felt -cw test.felt | php
Hello, world!

OK, if your output looks like the above then you are home and dry, but just to make sure let's convert it into JavaScript that would run under Node.js. You will of course need to have that installed on your system for this next bit to work:

First, let's render the same code as before but as Node.js code:

$ felt test.felt -as nodejscoder
console.log("Hello, world!\n");

$ # and this time we run it as well...
felt test.felt -as nodejscoder | node
Hello, world!

$ 

There! If that worked for you then you now have the capability to write PHP, JavaScript, Node.js code and CSS all from the same code-base. Hack and be happy!

Getting Help!

If this didn't work for you then please visit the Google Group "felt-hackers" and see if anybody can help you out. If that fails then please use the contact page and provide as much information about about your system, software versions etc. The definitive version of FELT can always be found in the VERSION file in the distribution.

MAN Page

I have produced a 'man' page that can be used so that when installed, you can type

man felt

and get some reasonably detailed help shown in the terminal window. How you install that page is entirely up to you but the simplest way is to locate it in the distribution and then just copy it so the "man.1" folder for your system.

I use Ubuntu and all I did was:

$ sudo cp felt.1 /usr/local/man/man1/felt.1