Tntnet quick start guide
Authors: Tommi Mäkitalo, Andreas Welchlin
This quick start guide includes:
- How to install tntnet
- Build and run your first application
- Explanation of this first application
- Further reading
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:
- configure.ac - the configuration file for autoconf
- Makefile.am - the rules to build the project with automake
- main.cpp - the file with the
main
function - myfirstproject.ecpp - our fist web page
- log.properties - configuration file for logging
- resources/myfirstproject.css - a static file of our web application
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.