Tntnet quick start guide

Authors: Tommi Mäkitalo, Andreas Welchlin

This quick start guide includes:

Tntnet is developed and tested on GNU/Linux. It is known to run on Sun Solaris, IBM AIX and FreeBSD.

Installation

You can install through the package manager in your operating system, if those packages are outdated (< cxxtools, tntnet 2.3), follow this instruction:

To install Tntnet you will first need to install cxxtools.

You can find cxxtools on the tntnet homepage and install it with:

$ tar xzf cxxtools-x.x.tar.gz
$ cd cxxtools-2.x
$ ./configure
$ make
$ sudo make install
$ sudo ldconfig

The same installation procedure is used for tntnet. Install it with:

$ tar xzf tntnet-x.x.tar.gz
$ cd tntnet-x.x
$ ./configure
$ make
$ sudo make install
$ sudo ldconfig

Now you have a working Tntnet environment.

How to create your first web application

To create a web application we need to create a project. The easiest way is to use the helper script tntnet-project. We execute on the command line:

$ tntnet-project myfirstproject

This creates a initial web project, which uses autotools as a build system. It is created in a directory named myfirstproject. The most interesting files, which are created are:

For quick information about autotools using, read this mini howto: http://www.niksula.hut.fi/~mkomu/docs/autohowto.html

To build and execute your first application enter the following commands:

$ cd myfirstproject
$ make
$ tntnet

Now you can start your web browser and navigate to http://localhost:8000/myfirstproject.

You can see the result of your first running tntnet application, which prints the name of the application.

What have we done?

The source file myfirstproject.ecpp has been translated to C++. This C++ program was used to build a shared library which contains the whole web application.

A tntnet web application is a simple web page with special tags like <$ ...$>. The ecpp compiler ecppc creates a C++ source file and a header file with the same base name. These contain a class which has also the same name as the file. You can look into the generated code if you want, and sometimes it is useful to read it for further understanding of tntnet applications. If the C++ compiler has problems with your application it is a good idea to first check the generated code.

The tags <$ ... $> output a C++ expression. The result of the expression is printed into the resulting page when the page is requested (on runtime). For this purpose, a std::ostream is used, so that the type of the result can be any object, which has an output operator operator<<(ostream&, T) defined.

The configuration file tntnet.xml contains the settings. The two most important ones are the definitions of the listeners and URL mappings.

The listeners define, on which interface tntnet waits for requests. You define an IP address of the local interface and a port. The IP address may be empty or omitted. If omitted tntnet listens on all local interfaces.

The mappings tell tntnet what to do with incoming requests. Without this entry tntnet answers every request with http error 404 – not found. A mapping maps the URL - which is sent from a web browser - to a tntnet component. A component is the piece of code, which is normally generated by the ecpp compiler (ecppc).

That's what we did above with myfirstproject.ecpp. Components are identified by their (class) name and the shared library which contains this class. We named our class "myfirstproject" and our shared library "myfirstproject.so". The component identifier is then myfirstproject@myfirstproject.

So the mapping tells tntnet to call this component, when the URL /test.html is requested.

How to add static files to your web application

Web applications typically contain static and dynamic content. Static files are images, css or javascript source files.

In the example application we already have a css file. All static files are located in the resources directory. When you add new files, add the to the top level Makefile.am under the variable staticSources also so that they are compiled into the web application.

All files specified this way are sent to the browser as is. No ecpp processing takes place.

After adding the files you have to compile the application and rerun it. Also after each change of a static file the application must be recompiled. Note also that the browser may cache static files so that you may need to deactivate or clear the cache to get the changed pages.

Adding dynamic files

Dynamic files are compiled into components and may contain all ecpp tags documented in the ecpp(7) man page.

Put them into your project and add them to the ecppSources variable into the Makefile.am.

Here also a recompile and rerun is needed after every change.

Where to go from here

The tool tntnet-project creates a project template. You may specify a different template for more sophisticated applications. Try tntnet-project -h to get help and tntnet-project -l to list the available templates. The templates contain a REAME.md, which shortly describes the structure of the created projects.