<!--toc-->
|
|
## Overview
|
|
The process of building CppCMS templates is following:
|
|
1. Compile all sources of specific view together into single C++ file using [cppcms\_tmpl\_cc](/wikipp/en/page/ref_utils#tmpl).
|
2. Compile C++ file into object file.
|
3. Link it together with program or create dynamically loadable object that can be loaded by CppCMS program.
|
|
## Creation of C++ code
|
|
Can be done by invoking [cppcms\_tmpl\_cc](/wikipp/en/page/ref_utils#tmpl) with a list of files, for example:
|
|
cppcms_tmpl_cc -o view.cpp main.tmpl page.tmpl article.tmpl
|
|
Note, when you derive classes from parents, you should compile them together in correct order.
|
|
For example for following hierarchy.
|
|
[master]
|
/ \
|
[page] [summary]
|
/ \ / \
|
[post] [info.] [archive] [recent_posts]
|
|
You should compile files as:
|
|
cppcms_tmpl_cc master.tmpl page.tmpl post.tmpl \
|
info.tmpl summary.tmpl archive.tmpl \
|
recent_posts.tmpl -o my_view.cpp
|
|
When you share some templates between various skins, and compile all then in namespace `vary`. You should specify parameter: `-n view_name`.
|
|
By default, templates compiler puts all translation strings in the domain that is named by template name. So if you compile with `-n skin1` all you strings would be taken from
|
`skin1` domain. It can be overridden by specifying `-d domain_name` switch.
|
|
Generally you want to put all templates to same domain as the main program.
|
|
## How templates are loaded
|
|
Each C++ file that is generated from the template includes
|
static global constructor that registers all classes of specific view in `libcppcms`.
|
|
When programmer wants to use come class from specific view
|
he calls `render()` function of `worker_thread` class that
|
seeks for registered views and uses them.
|
|
Thus, everything you need to do is link this object with your library or load it dynamically.
|
|
## Static Linking with Compiled Object
|
|
This is the simplest way to add the template, for example:
|
|
cppcms_tmpl_cc -o view.cpp master.tmpl ...
|
g++ -O2 -Wall view.cpp -o view.o
|
g++ application_objects.o view.o -lcppcms -o app
|
|
## Using Libraries of Views
|
|
Sometimes, you may create a library of several views and try
|
to link with them. For example:
|
|
g++ -fPIC -DPIC view1.cpp -o view1.o
|
g++ -fPIC -DPIC view2.cpp -o view2.o
|
g++ -shared view1.o view2.o -lcppcms -o libview.so
|
|
Now you link this library directly with your program:
|
|
g++ application_objects.o -L. -lview -lcppcms -o app
|
|
You can also create static library and link with it.
|
|
g++ view1.cpp -o view1.o
|
g++ view2.cpp -o view2.o
|
ar cru libview.a view1.o view2.o
|
ranlib libview.a
|
|
__Now, if you link *static* the library as is, it would not work!!!__ At least with GNU linker.
|
|
GNU linker "optimizes" the code and discovers that there
|
is no symbols in application objects that refer to the
|
symbols of libview.a and would not include it in link process.
|
|
In order to make everything work you should link as following:
|
|
g++ application_objects.o \
|
-Wl,--whole-archive libview.a -Wl,--no-whole-archive \
|
-lcppcms -o app
|
|
It would force the linker include all objects form libview.a and cause everything work correctly.
|
|
_Note:_ You do not need this for dynamically loaded libraries like so or dll. Because, by default they include
|
whole archive.
|
|
## Dynamic Loading of Views
|
|
You have an option load all views dynamically from shared object or dll. This option have following restrictions:
|
|
1. You should compile your program with `--export-dynamic` option, otherwise dynamic casting would not work and you'll get error "incorrect content type" trying to render your views.
|
2. Windows/Cygwin has strong restriction on undefined symbols in dll's. Thus you should not refer directly to any non-virtual member functions of your content objects, otherwise you would get linker errors trying to build dll.
|
|
For example:
|
|
Build your loadable view:
|
|
cppcms_tmpl_cc -o view.cpp master.tmpl ...
|
g++ -fPIC -DPIC view.cpp -o view.o
|
g++ -shared view.o -lcppcms -o libview.so
|
|
Link your program
|
|
g++ --export-dynamic app_objects.o -lcppcms -o app
|
|
Now add to your [configuration file](/wikipp/en/page/ref_utils#tmpl) path to directory where
|
libview.so is placed:
|
|
templates.dirs = { "/usr/local/lib/youapp" }
|
|
When application starts, it would try to load **any** shared
|
object that is placed in this path. Thus, it is not good
|
idea to save put your views into directory with other
|
non-related libraries.
|
|
|
