-
Notifications
You must be signed in to change notification settings - Fork 13
Developer Handbook
This document is exclusively intended for people who are developing Thali itself. This document is not for those who wish to build apps on top of Thali.
Go off to https://github.com/thaliproject/ and after you login with your GitHub account please go to each of the projects and hit 'watch'. We don't send out emails with notifications of PRs, issues, builds, etc. We use GitHub for that. So you need to be set up to watch (and make sure your settings at GitHub are that you should be emailed when a watch even happens) or you will miss what's going on.
Next go here. That is where we keep our backlog. If you are officially part of the project then go bug Yaron to set up an account for you so you can be assigned items. By default however it is world readable so anyone can track what we are up to.
Right now we are investigating re-writing the whole project in Javascript. The idea is that this will let us run everywhere. The plan is to build the CouchDB functionality using PouchDB running on Node. This means getting Node running everywhere but there seems to be a will to make that happen. We'll see. In any case this section is a place I'm using for notes about what technologies I want to use with Javascript.
From a testing perspective http://www.clock.co.uk/blog/tools-for-unit-testing-and-quality-assurance-in-node-js seems very useful. I've done some investigation of the technologies they recommend and they do seem like the best choices for node.js. So we'll start there.
To use mocha in Intellij we have to install the node.js plugin and then go to Run->Configurations and hit the green arrow and add Mocha. The actual location of Mocha depends on how exactly it was installed. If it was installed globally (e.g. npm install -g mocha) then it should hang out in c:\Users\x\AppData\Roaming\npm\node_modules\mocha.
Make sure to run "npm install" in the root of the project before running tests or anything else so all of our dependencies are loaded.
I like Chai and it's expect design more than should.js and Chai also has a nice story for promises (which I'm sure should.js has somewhere but I didn't find it) so I decided to use Chai and expect instead.
ONLY RUN NPM FROM INSIDE OF THE GIT (READ: MINGW32) COMMAND SHELL!!! Running NPM from a normal Windows shell causes really odd behaviors and install failures. I strongly suspect that some of the dependencies we are using are using shell scripts or similar for install that aren't Windows friendly but seem to run o.k. inside the MINGW32 environment that comes with GIT.
To build node on windows just follow the instructions here and yes, it really is that easy. I'm now experimenting with building for android following the instructions here. I'm going to try the android build on Windows using the MINGW32 window to handle the bash script but if that doesn't work then I'll try it on Linux since I have a VM handy. The first step is to install the Android NDK. Since 64 bit Android phones are just now coming out I will focus on getting the 32 bit targeted NDK for my 64 bit Windows (yeah, I know, confusing). Unfortunately a issue with the eval command in prebuild-common.sh (line 193) caused a failure on Windows. At some point I should actually investigate this but for now I'll take the cowards way out and run to Linux. Yeah, I could try Cygwin or something, but right now I just want to get things going on Android. I can get fancy later. So this means cloning node onto Linux, downloading the 32 bit SDK targeted at 64 bit Ubuntu (since I'm using 64 bit elementary OS). Running the script failed with a complaint that there is no target arm-linux-androidabi-4.7, but there is a 4.6 and a 4.8. A quick edit of android-configure (in Node root) fixed that.
Our first dependency is Tor_Onion_Proxy_Library. It contains three sub-projects, universal, java and android. Most of the code lives in universal who builds a JAR that then the java and android projects depend on. The java project then produces a Jar apps can use to enable themselves with Tor and android produces an AAR for the same purpose.
Next up is our CouchBase forks. These contain custom versions of CouchBase with extensions we need. The dependency structure is:
couchbase-lite-java-native <- couchbase-lite-java-core <- couchbase-lite-listener
<- couchbase-lite-java
<- couchbase-lite-android
We then have the Thali project which is where we build the TDH. Right now there is an odd structure in there involving two root directories, Production and Prototype. When we resolve https://www.pivotaltracker.com/story/show/78493988 we will get rid of Prototype and hoist the contents of Production to the root. For now we will ignore Prototype.
Thali
-Production
-Utilities
-UniversalUtilities
-JavaUtilities
-AndroidUtilities
-DotNetUtilities
-WindowsStoreUtilities
Of these right now active development is focused on UniversalUtilities, JavaUtilities and AndroidUtilities. They have the same relationship as the similarly named projects in Tor_Onion_Proxy_Library. The bulk of the logic is in UniversalUtilities which produces a jar consumed by JavaUtilities and AndroidUtilities who themselves produce a Jar and AAR respectively.
This then takes us to:
Thali
-Production
-ThaliDeviceHub
-Universal
-android
-java
Same structure as before.
The ThaliHTML5ApplicationFramework contains three key directories, web, Java and Android. The relationship here is slightly different as both Java and Android will cause web to build (it's a bunch of bower scripts) and then copy the files they need.
The thali-addressbook depo is actually a fork of the ThaliHTML5ApplicationFramework. So it's structured the same way. Eventually we expect this project to be folded into the Thali project.
Please note that we have standardized on gradle for our build environment and that no IDE specific code is to be checked in.
We publish releases and binaries so this section is only needed for people who are actually developing Thali so they can make changes locally.
The most sane way to handle things until we have Jenkins automating our builds is to use the global build script. To do this one has to:
-
Go to https://github.com/thaliproject/ and fork everything in sight
-
On your dev machine clone all your forks into the same directory
-
Set up your gradle.properties as explained in Understanding Thalis Use of Maven
-
Now go to the thali clone and run "thali\Production\gradlew installAll"
This will build everything the TDHs need including the Tor library, all the couchbase libraries, and all the Thali libraries. What it won't build is the address book or the Thali HTML5 app template. We'll talk about them in the next section.
It's worth looking at thali\Production\build.gradle as it contains various useful options including ones to turn off tests and do global cleans.
Since one is a fork of the other they both build in the same way. You need to go to "ThaliHTML5ApplicationFramework\gradlew buildAll" and everything will be built. Note that the Android build takes 2 or 3 minutes. So during development I'll typically just call "ThaliHTML5ApplicationFramework\gradlew :java:installApp" to save time.
Make sure to review these links as they have all sorts of annoying bits of information needed to actually build things.
Understanding Thalis Use of Maven
Building all of our CouchBase Dependencies
Building all of our Java Thali Projects
The code here hasn't had much love recently so this section should be considered historical.
Right now we are using stock PouchDB. We just keep this section around if we have to remember how we used to build our own version.
We need a bunch of software. We use IntelliJ Ultimate Edition although I'm told that the (free) community edition supports what we do just fine. In addition one needs the latest JDK, latest Android SDK, a local maven installation, gradle and a decent android emulator and/or device.
We have a bunch of instructions on how to get this software for Windows, see set up for windows but we have tested everything on Mac and Linux and it all runs just fine there as well.
NOTE: EVEN IF YOU AREN'T RUNNING ON WINDOWS STILL READ THE set up for windows BECAUSE IT CONTAINS IMPORTANT CONFIGURATION INSTRUCTIONS THAT APPLY TO ALL PLATFORMS
Thali Guide to Git has a bunch of information about how we use git but anyone who has used git regularly isn't going to find anything new there.
Please see Guide to Debugging for more information than you could ever want on how debugging works across our various dependencies.
Just install the latest from here. It automatically updates itself anyway so I don't worry about what version I'm running.
See Android Emulator
See Application Development in Thali
See Tips and Tricks
See Scratchpad