Terra for C Programmers

Terra's features are very similar to C, and thus the easiest way to learn what terra can do is to compare it to C.

Note: This page is about the actual terra code, used inside terra functions. Terra has many more lua- and metaprogramming-related features not documented here.

#Types

C	terra
int, int8_t, int16_t, int32_t, int64_t	int, int8, int16, int32, int64
unsigned int, uint8_t, uint16_t, uint32_t, uint64_t	uint, uint8, uint16, uint32, uint64
stdbool.h bool	bool
float, double	float, double

#Features

Feature	C	terra	Remark
Function Declaration	void main(int argc, char** argv) {  [...] }	terra main(argc : int, argv : &rawstring)  [...] end
Variable Declaration	int foo	var foo : int
Type Inference	int foo = 10;	var foo = 10
Strings	int foo = "abc";	var foo = "abc" var foo= 'abc'	As in lua, both " and ' can be used to delimit strings.
Characters	char foo = 'a';	var foo = "a"[0]	Character literals seem not to be supported.
Pointer Types	int *foo;	var foo : &int
Dereferencing	a = *foo;	a = @foo
Adress Of	a = &foo;	a = &foo
Function Pointer Types	int (*fname)(bool, char)	fname : {bool, char}->int	Multi-returns are also possible, e.g. {bool, char}->{int,char}
Global Variable Declaration	int foo = 10;	global("foo", 10)	Must be called in lua context
Access Global Variables	foo = 10; a = foo;	[foo] = 10; a = [foo]	See Escapes
Include	#include "foo.h"	terralib.includec "foo.h"	Must be called in lua context
Linking	ld on the command line	terralib.linklibrary("libraryname")	Must be called in lua context. See footnote [1]
Struct Declaration	struct bar {  int foo;  int baz }	struct bar {  foo : int;  baz : int }	Must be defined outside function. Members must be separated by ";"
Unions	struct bar {  union un {   int foo;   int baz  } }	struct bar {  union un {   foo : int;   baz : int  } }	Only applicable inside struct.
Member Access	foo.bar	foo.bar
Struct Pointer Access	foo->bar	foo.bar
sizeof	sizeof(int); sizeof(int*);	sizeof(int) sizeof([&int])	See Escapes

[1] Terra also has two more options for linking:

• Directly output ".o" files, which can be linked the traditional way.
• Embed terra into your C application, and link your required libraries while building it.

To load libraries from your current working directory on linux, add it to your LD_LIBRARY_PATH environment variable.

#Escapes One thing to look out for when using terra are escapes. They are explained in detail here.

In essence, any type and global variable in terra is a lua value. The fact that something should be a lua value can be explicitly stated by surrounding it with [ ].

Usually the compiler notices lua values by itself, e.g. var a : &int, but in other cases you have to give it a helping hand, e.g. sizeof([&int]) or printf("%s\n", [myglobal]).

#Example Terra mixes lua with a low-level programming language, so it can be a bit confusing to set it up. Here's a "boilerplate" example to get you started.

-- include a few C headers
local C = terralib.includec("stdio.h")
local SDL = terralib.includec("SDL/SDL.h")

-- include a C library
terralib.linklibrary("libSDL.so")

-- define a global
global("foo", 50)

terra main()
    C.printf("hello, world\nglobal foo=%d\n", [foo])
end

main()