Skip to content

node

Jump to bottom Edit New page
Martin Carlberg edited this page Sep 18, 2023 · 50 revisions

We now have a beta version of the Cappuccino frameworks working under Node.js.
This is a comprehensive alternative to the JVM-based Narwhal toolchain and, as such, deprecates it.
It is feature complete and now suitable (in some cases) for production use. It includes our new compiler/parser that supports ECMAScript 2022.

Install using npm package for all user accounts

To try it out please do the following:

  1. Install Node.js, if not already present. The Cappuccino project targets the current LTS version of Node.js. Other versions may work, but are not necessarily tested. Use either the canonical installer or the operating system package manager of your choice. Be really sure your Node (including npm) is the active LTS version.
  2. Make sure you can install global npm modules. We recommend you run npm set prefix ~/.npm to set the install location in your home directory; default otherwise is /usr/local/ that might requires running everything with sudo. It depends on what OS version you are using.
  3. Make sure to setup the PATH environment variable for the above install location. If the recommended way above is used you should add the line export PATH="$HOME/.npm/bin:$PATH" as last line in your .zshrc file or equivalent config file.
  4. Restart your shell.
  5. Run npm install -g @objj/cappuccino

You should now have the Node version installed. Type which capp and check that the installed version points to the above prefix path. If the recommended way above is used it should point to ~/.npm/bin/capp. You might need to restart the shell before it finds the correct path.

To generate a new project try:

capp gen HelloWorld
cd HelloWorld
python3 -m http.server

Go to http://localhost:8000 in your browser to run the application.

The Cappuccino frameworks will be installed at ~/.npm/lib/node_modules/@objj/cappuccino/dist/cappuccino/Frameworks and ~/.npm/lib/node_modules/@objj/cappuccino/dist/objective-j/Frameworks

Install from source for all user accounts after installing npm package

To build Cappuccino from source you can set the environment variable CAPP_BUILD to where the build directory should be. If it is not set you can make sure it is all the time by adding the line export CAPP_BUILD="/path/to/cappuccino/build/directory" to your .zshrc or equivalent config file. Don't forget to restart your shell. If you don't set CAPP_BUILD it will create a Build directory in the repository.

Do the following in the Terminal:

git clone https://github.com/cappuccino/cappuccino.git
cd cappuccino
git checkout node
npm install
npm update
jake install

Type which capp and check that the installed version points to the above prefix path. If the recommended way above is used it should point to ~/.npm/bin/capp. You might need to restart the shell before it finds the correct path.

The Cappuccino frameworks will be installed at dist/cappuccino/Frameworks and dist/objective-j/Frameworks. Tools will be in dist/cappuccino/bin and dist/objective-j/bin. They are also available in the build directory. The tools are also installed in the above prefix path.

To run the test cases after the above jake install type the following in the Terminal:

jake test-only

Install from source for current user only without previously installing npm package.

You don't need to first install with npm. It will allow you to have different versions installed at the same time. It is also a lot cleaner as nothing is installed at a global scope like /usr/local/ or at your npm prefix path.

To build Cappuccino from source you can set the environment variable CAPP_BUILD to where the build directory should be. If it is not set you can make sure it is all the time by adding the line export CAPP_BUILD="/path/to/cappuccino/build/directory" to your .zshrc or equivalent config file. Don't forget to restart your shell. If you don't set CAPP_BUILD it will create a Build directory in the repository.

Do the following in the Terminal:

git clone https://github.com/cappuccino/cappuccino.git
cd cappuccino
git checkout node
npm install
export PATH="$PWD/dist/cappuccino/bin:$PWD/dist/objective-j/bin:$PATH"
jake dist

The Cappuccino frameworks will be installed at dist/cappuccino/Frameworks and dist/objective-j/Frameworks. Tools will be in dist/cappuccino/bin and dist/objective-j/bin. They are also available in the build directory.

To run the test cases after the above jake dist type the following in the Terminal:

jake test-only

If you want to use this version of Cappuccino from every new Terminal windows make sure to setup the PATH environment variable for the above two paths to the tools locations. You could add the line export PATH="<PathToCappuccino>/dist/cappuccino/bin:<PathToCappuccino>/dist/objective-j/bin:$PATH" as last line in your .zshrc file or equivalent config file. Don't forget to restart your shell. This is not needed if you just want to use it in the current Terminal window.

There are some tools that are not yet ready and are not working. Some examples are:

  1. capp_lint
  2. ...

Build your own project

To build your own project with this new version you need to update your Jakefile. Please check what a new Jakefile looks like by generate a new project with the tool capp gen … as described above.

FAQ

Where is everything installed now when the narwhal directory does not exist anymore?

We have introduced a new dist directory where everything is installed. There are two places where it can exist. If you have downloaded the repository from Github a local dist directory will be at the root of the repository. There can also be a global dist directory if you install with npm install @objj/cappuccino or build with jake install. It will be placed at the npm prefix path. Check npm prefix -g to find out where (Example: ~/.npm/lib/node_modules/@objj/cappuccino/dist). If you want to build without installing in the global dist directory you can build with jake dist. It will only install in the local dist directory and is an excellent way of keeping a sandboxed version.

Is the Node version the same as the latest master?

There is no change at all to the AppKit or the Foundation. So there are no changes to how your app will run against the frameworks. The only change is the tools that build things like jake and nib2cib etc. The way they build things are still exactly the same. It is only narwhal that is replaced with Node. What is for example how we read and write a file etc. So code is replace in the tools to use Node api instead of Narwhal api. One major thing is also that Node is asynchronous by default. This means that we had to add support for async / await to be able to handle some cases in the tools in an elegant way.

How can I use this new cool async / await support in my project?

The new async / await support is only available in the Node version and is based on async / await for Javascript. Syntax has been added to declare an Objective-J method as an async method. This is best shown as an example:

- (async CPView)getMyView {
    var aView = await [self loadTopView];

    if (aView) {
        [self addViewAsTop:aView];
    } else {
        aView = [[CPView alloc] initWithFrame:CGRectMake(0, 0, 200, 200)];
    }

    return aView;
}

For more info on new language features please check ea2022

Is the Node version stable?

The Node version is stable and is used by multiple developers in their projects. Some tools are not yet converted to Node but the most common are. When all tools are converted the Node version will move from a beta version to a major version.

Does the Node version work with the latest version of Xcode?

The Node branch offers the same integration with Xcode/Interface Builder as the Narwhal branch. Cappuccino's nib2cib tool uses Apple's ibtool and plutil to perform intermediate transformations of xibs prior to converting them to cib format. Recent versions of Xcode (with which the two Apple utilities are packaged) have caused this intermediate transformation to fail when the xib's deployment target is set to a value more recent than 'macOS 12.2 and later'. Resetting the xib's 'Builds for' value to 'macOS 12.2 and later' or any previous value will circumvent this behaviour. The setting has no effect on the xib/cib behaviour when used for Cappuccino. The problem has been permanently corrected by Pull Request 3056 and tested with Xcode versions up to and including 15.0

What version of JavaScript syntax can be used with the Node version?

The Node version supports ES2022 syntax for JavaScript along with async / await.

For more info on new language features please check ea2022

Add a custom footer
Add a custom sidebar
Clone this wiki locally