iCoreTech Research Labs Just a placeholder

Creating a Cappuccino application with capp

This is the second part of the Cappuccino bits series.

1. Installing Cappuccino from source.
2. Creating a Cappuccino application with capp.
3. Playing with a Cappuccino project (TBA)

If you missed the part 1 I suggest reading it now before proceeding. If you don't at least be sure you did understand the meaning of CAPP_BUILD and have it correctly setup.

capp is a dual utility that can help in generating your application and setting some environmental variables that Cappuccino will use. It's part of Cappuccino's Tools.

First, let's take a look at the config options it can set:

• user.name
• user.email
• organization.name
• organization.url
• organization.email
• organization.identifier

You can get a view of what config options are already set with:

capp config -l

Start setting your config options with command:

capp config key "value"

where key is one of the values shown above, and value is actually what you want to be in the chosen key.

capp config user.name "Claudio Poli"
capp config organization.name "iCoreTech Research Labs"

Those will be used, for example, in the comments when an application gets generated by the capp command.

While config options' description is pretty straightforward it should be noted that organization.identifier is the less recognizable; it's the reserved domain identifier, commonly used when creating Mac applications.
You can set it to the format "com.mycompany" or "org.bestcompany", then if you create a project called MyApp its identifier becomes "com.mycompany.MyApp".

It's worth noticing that you can see a single option value by running:

capp config --get key

where key is one of the options I wrote above, even though you may just well want capp config -l (or --list).

Once we setup our capp environment, we can go hands down in creating a whole new application.

If you run

capp -h

you can see a helpful guide on how to use capp.

Now, instead of using "capp config" we are going to use the generator part, namely "capp gen".

In the small usage banner after gen PATH we can see some options we can use, so pick the one you need, explained below:

capp gen MyWebSite

This will create a directory MyWebSite in the current directory you are currently in when you executed capp.
Of course you can also supply a full path instead of MyWebSite.
The generated application is a bare-metal Cappuccino/Objective-j application, called by the templating system "Application".
No xib/nib/cib files here, the initial code in Application.j is instructed to just show the basics.

Also note that in the MyWebSite directory there's a folder called Framework. That's right, capp gen PATH without further parameters copy the entire frameworks from a previous Cappuccino installation (see the part 1 of the tutorial) to your project.

This may be desiderable when working on a stable version, however we would like to have the entire framework symlinked to a special directory that we are interested in keeping up to date with recent Cappuccino changes.

In order to accomplish that, run:

capp gen MyWebSite -l

This will be still a bare-metal application, but if you go into Frameworks directory you'll notice that AppKit, Foundation and Objective-J folders are simbolic links:

22:51 ~/Sites/MyWebSite/Frameworks $ ls -lha
total 24
drwxr-xr-x   6 kain  staff   204B 21 Ott 22:50 .
drwxr-xr-x  11 kain  staff   374B 21 Ott 22:50 ..
lrwxr-xr-x   1 kain  staff    51B 21 Ott 22:50 AppKit -> /Users/kain/src/cappuccino_framework/Release/AppKit
drwxr-xr-x   5 kain  staff   170B 21 Ott 22:50 Debug
lrwxr-xr-x   1 kain  staff    55B 21 Ott 22:50 Foundation -> /Users/kain/src/cappuccino_framework/Release/Foundation
lrwxr-xr-x   1 kain  staff    56B 21 Ott 22:50 Objective-J -> /Users/kain/src/cappuccino_framework/Release/Objective-J

This explains why the CAPP_BUILD env variable is so important even before trying to install Cappuccino Tools.

If instead of generating a whole application we only need to put Frameworks files in place we can run:

capp gen MyWebSite -f

Instead of -f you can use the verbose --frameworks, add -l for some extra, already explained, fun.

Ideally if you want to keep Cappuccino up to date you should follow the instructions in part 1 to git pull and recompile the framework.

This is the last option we will be covering for today, and it's the one used to generate a project by using a Template.

You can see the actual list of templates by listing the contents of a specific directory:

ls -lha /usr/local/share/narwhal/packages/objj/lib/capp/Resources/Templates

You will see three templates:

• Application
• NibApplication
• ThemeDescriptor

When creating your application you can choose your template by using the -t switch, so for example:

capp gen MyWebSite -t NibApplication

Application is the code generated when the -t switch is omitted.

NibApplication is an application skeleton that already implements code for running a nib/cib/xib based application, included in Resources. Also the Application.j and other files' code is different.
For example Application.j contains a member variable that references a CPWindow, already in the nib file, and awakeFromCib is instructed to make the window go fullBridge, meaning full browser window. In this kind of application the graphics user interface is left in the nib file.

ThemeDescriptor is a special project for creating custom Cappuccino themes.

Tutorials ends here, thanks for reading. As usual feedback is appreciated.

Next: playing with a Cappuccino project.

Cappuccino logo used with permission. Cappuccino is a trademark of 280 North.