Island fully supports out-of-tree builds. While the term "out-of-tree" is a bit ambiguous, for this discussion it means that you can place your app directory alongside the main Island repository and keep track of Island and your app code in separate directories.
This works by updating the CMakeLists.txt variable ISLAND_BASE_DIR to the relative path pointing from your app base directory to the Island base directory.
Sometimes it can be a good idea to add Island as a submodule to your application repository. For this to work, you will have to update your app's ISLAND_BASE_DIR setting (see Hint 1).
Say, you set up a directory structure as follows:
+ my_island_project
\
|- island @47b892 (git submodule via: https://github.com/tgfrerer/island.git)
|
|- extra_modules @be2823 (git submodule via https://github.com/some_user/island_modules.git)
| \
| |- le_frobnicate
| |
| |- le_bafurcate
|
|- my_apps
| \
| |- my_test_app_1
| |
| |- my_test_app_2
You get Known-Good versions for all your Island app dependencies.
If you create a my_island_project git repository, and then add to it the main island repository as a git submodule, this allows you to store a Known Good version of Island with your app. If someone else then clones your project and (checks out all submodules recursively) they will get exaclty the right versions of Island and any other dependencies.
Sometimes the modules coming pre-packaged with Island are not enough - either you want to use your own modules library or you might want to use modules, made available from other folks.
This is possible via the add_island_module_location() macro which you can call from your app's CMakeLists.txt file. See Example. You can add one or more paths so that these will be scanned additionally when Island searches for modules.
Then, call add_island_module(my_extra_module_name) to add your custom module, just as you would add any Island core module. Similarly to how it's done here, but in your app's CMakeLists.txt file. If you're using Qt Creator, you should see the module added to your source file view immediately as soon as you save the CMakeLists.txt file.
Similarly to checking in the main Island repository as a submodule to your app repository (See: Hint 1), adding extra module source directories as submodules can help you keep track of extra modules used for a particular project.