← Back to branch summary

~sethj/ubuntu/wily/unity/fix-for-1445595

« back to all changes in this revision

Viewing changes to cmake/vala/README.rst

Add build stuff for vala

Show diffs side-by-side

added added

removed removed

Lines of Context:
cmake/vala/README.rst
 
1
==========
 
2
Vala CMake
 
3
==========
 
4
:Author: 
 
5
    Jakob Westhoff
 
6
:Version:
 
7
    Draft
 
8
 
 
9
 
 
10
Overview
 
11
========
 
12
 
 
13
Vala CMake is a collection of macros for the CMake_ build system to allow the
 
14
creation and management of projects developed using the Vala_ programming
 
15
language or its "Genie" flavor (less tested).
 
16
 
 
17
 
 
18
Installation
 
19
============
 
20
 
 
21
To use the Vala macros in your own project you need to copy the macro files to
 
22
an arbitrary folder in your projects directory and reference them in your
 
23
``CMakeLists.txt`` file.
 
24
 
 
25
Assuming the macros are stored under ``cmake/vala`` in your projects folder you
 
26
need to add the following information to your base ``CMakeLists.txt``::
 
27
 
 
28
    list(APPEND CMAKE_MODULE_PATH 
 
29
        ${CMAKE_SOURCE_DIR}/cmake/vala
 
30
    )
 
31
 
 
32
After the new module path as been added you can simply include the provided
 
33
modules or use the provided find routines.
 
34
 
 
35
 
 
36
Finding Vala
 
37
============
 
38
 
 
39
The find module for vala works like any other Find module in CMake.
 
40
You can use it by simply calling the usual ``find_package`` function. Default
 
41
parameters like ``REQUIRED`` and ``QUIETLY`` are supported.
 
42
 
 
43
::
 
44
 
 
45
    find_package(Vala REQUIRED)
 
46
 
 
47
After a successful call to the find_package function the following variables 
 
48
will be set:
 
49
 
 
50
VALA_FOUND
 
51
    Whether the vala compiler has been found or not
 
52
 
 
53
VALA_EXECUTABLE
 
54
    Full path to the valac executable if it has been found
 
55
 
 
56
VALA_VERSION
 
57
    Version number of the available valac
 
58
 
 
59
 
 
60
Precompiling Vala sources
 
61
=========================
 
62
 
 
63
CMake is mainly supposed to handle c or c++ based projects. Luckily every vala
 
64
program is translated into plain c code using the vala compiler, followed by
 
65
normal compilation of the generated c program using gcc.
 
66
 
 
67
The macro ``vala_precompile`` uses that fact to create c files from your .vala
 
68
sources for further CMake processing. 
 
69
 
 
70
The first parameter provided is a variable, which will be filled with a list of
 
71
c files outputted by the vala compiler. This list can than be used in
 
72
conjunction with functions like ``add_executable`` or others to create the
 
73
necessary compile rules with CMake.
 
74
 
 
75
The initial variable is followed by a list of .vala files to be compiled.
 
76
Please take care to add every vala file belonging to the currently compiled
 
77
project or library as Vala will otherwise not be able to resolve all
 
78
dependencies.
 
79
 
 
80
The following sections may be specified afterwards to provide certain options
 
81
to the vala compiler:
 
82
 
 
83
PACKAGES  
 
84
    A list of vala packages/libraries to be used during the compile cycle. The
 
85
    package names are exactly the same, as they would be passed to the valac
 
86
    "--pkg=" option.
 
87
 
 
88
OPTIONS
 
89
    A list of optional options to be passed to the valac executable. This can be
 
90
    used to pass "--thread" for example to enable multi-threading support.
 
91
 
 
92
DIRECTORY
 
93
    Specify the directory where the output source files will be stored. If 
 
94
    ommitted, the source files will be stored in CMAKE_CURRENT_BINARY_DIR.
 
95
 
 
96
CUSTOM_VAPIS
 
97
    A list of custom vapi files to be included for compilation. This can be
 
98
    useful to include freshly created vala libraries without having to install
 
99
    them in the system.
 
100
 
 
101
GENERATE_VAPI
 
102
    Pass all the needed flags to the compiler to create an internal vapi for
 
103
    the compiled library. The provided name will be used for this and a
 
104
    <provided_name>.vapi file will be created.
 
105
 
 
106
GENERATE_HEADER
 
107
    Let the compiler generate a header file for the compiled code. There will
 
108
    be a header file as well as an internal header file being generated called
 
109
    <provided_name>.h and <provided_name>_internal.h
 
110
 
 
111
The following call is a simple example to the vala_precompile macro showing an
 
112
example to every of the optional sections::
 
113
 
 
114
    vala_precompile(VALA_C
 
115
        source1.vala
 
116
        source2.vala
 
117
        source3.vala
 
118
    PACKAGES
 
119
        gtk+-2.0
 
120
        gio-1.0
 
121
        posix
 
122
    OPTIONS
 
123
        --thread
 
124
    CUSTOM_VAPIS
 
125
        some_vapi.vapi
 
126
    GENERATE_VAPI
 
127
        myvapi
 
128
    GENERATE_HEADER
 
129
        myheader
 
130
    )
 
131
 
 
132
Most important is the variable VALA_C which will contain all the generated c
 
133
file names after the call. The easiest way to use this information is to tell
 
134
CMake to create an executable out of it.
 
135
 
 
136
::
 
137
 
 
138
    add_executable(myexecutable ${VALA_C})
 
139
 
 
140
 
 
141
Further reading
 
142
===============
 
143
 
 
144
The `Pdf Presenter Console`__ , which is a vala based project of mine, makes
 
145
heavy usage of the here described macros.  To look at a real world example of
 
146
these macros the mentioned project is the right place to take a look. The svn
 
147
trunk of it can be found at::
 
148
 
 
149
        svn://pureenergy.cc/pdf_presenter_console/trunk
 
150
 
 
151
 
 
152
__ http://westhoffswelt.de/projects/pdf_presenter_console.html
 
153
 
 
154
 
 
155
Acknowledgments
 
156
===============
 
157
 
 
158
Thanks go out to Florian Sowade, a fellow local PHP-Usergroupie, who helped me
 
159
a lot with the initial version of this macros and always answered my mostly
 
160
dumb CMake questions.
 
161
 
 
162
.. _CMake: http://cmake.org
 
163
.. _Vala: http://live.gnome.org/Vala
 
164
.. _Genie: http://live.gnome.org/Genie
 
165
 
 
166
 
 
167
 
 
168
..
 
169
   Local Variables:
 
170
   mode: rst
 
171
   fill-column: 79
 
172
   End: 
 
173
   vim: et syn=rst tw=79