Porting
=======

FRT is a modular system, and FRT modules can be developed and tested mostly in
isolation, without compiling them as part of Godot. The idea is that
developing and testing a module can be done on a real board with a very quick
test cycle. Once the module is tested, it can be compiled as part of Godot.

As an example, compiling and linking every FRT module from scratch takes less
than 5 seconds on a Pi 2. Relinking them takes less than 1 second.
As another example, compiling and linking the `video_fbdev` module on a
A10-based board takes less than 3 seconds.

Modules don't need to be generic. For example, you could access a custom
device via GPIO and make a custom module implementing the `frt::Keyboard`
interface. You can then use it instead of one of the standard keyboard
modules.

## Compiling and Testing a Module

To get familiar with the process, here is how to compile and test the
`mouse_x11` module on a Linux debian desktop. Either clone the repository
or uncompress the FRT source tarball:

	$ git clone https://github.com/efornara/frt
	$ cd frt

The X11 FRT modules can dynamically load the `libX11.so` library. The loading
code is not included in the repository and it is generated by a python script.

If you have python available, you can generate the loading code like this:

	$ cd dl
	$ ./procdl.py x11.dl

You will then have to compile and link the generated `x11.gen.cpp` file.

If you don't have python available, you can use a shell script that generates
a mock `x11.gen.h` file instead:

	$ ./minidl.py x11.dl

In this case, there is no 'x11.gen.cpp` file to compile and link.

In the `porting` directory, there is a sample `Makefile`. It has been written
so that there shouldn't be a need to change it. Instead, changes can be made
to the `Local.mk` file. If you are using git, you don't need to commit the
file to the repository and you can just soft-link the real one to it:

	$ cd ../porting
	$ make local
	git update-index --assume-unchanged Local.mk
	$ touch Test.mk
	$ ln -sf Test.mk Local.mk

Here is an example `Test.mk` for the python-generated dynamic loading code.

	OBJS += test_mouse.o mouse_x11.o x11.gen.o
	LIBS += -ldl

And here is an example `Test.mk` for the mock dynamic loading header:

	OBJS += test_mouse.o mouse_x11.o
	LIBS += -lX11

You can then compile and test the module like this:

	$ make run

## Tips

- If you have a powerful board, consider starting the Godot compilation in
  background, making sure to choose compilation options carefully as changing
  them later can trigger a full recompile. Also, make sure that ALSA and udev
  are enabled (if you need them).

- If you don't have a powerful board, consider cross compiling.

- If you need to add preprocessor definitions or special include directories to
  the compiler command line, add them in the cloned `frt_env` environment
  defined in `SCsub`. This way, they will only be used when compiling the files
  in `platform/frt` and changing them will not trigger a full recompile.