Instructions

This project is (initially) generated by eliom-distillery as the basic project pdldemo.

Note that external dependencies are required prior to building the project. Postgres is mandatory. By default, NPM is used for automatically installing various NPM packages; you can disable this via the USE_NPM variable in Makefile.options if you prefer to use a system-wide NPM installation. SASS is optional, but not installing it may negatively impact the rendering of the pages generated. All needed system packages (Postgres, NPM, SASS, ...) can be installed via the command

opam depext ocsigen-start

If you have issues with the NPM provided by your distribution, you can use NVM. If NPM is too old (< 2.0), you can try updating it with sudo npm install -g npm. Depending on your setup, you may have to update your $PATH for the new npm to become visible.

Generally, you can compile it and run ocsigenserver on it by

make db-init
make db-create
make db-schema
make test.byte (or test.opt)

Then connect to http://localhost:8080 to see the running app skeleton. Registration will work only if sendmail if configured on your system. But the default template will print the activation link on the standard output to make it possible for you to create your first users (remove this!).

See below for other useful targets for make.

Generated files

The following files in this directory have been generated by eliom-distillery:

• pdldemo*.eliom[i] Initial source file of the project. All Eliom files (*.eliom, *.eliomi) in this directory are automatically compiled and included in the application. To add a .ml/.mli file to your project, append it to the variable SERVER_FILES or CLIENT_FILES in Makefile.options.

• static/. This folder contains the static data for your app. The content will be copied into the static file directory of the server and included in the mobile app. Put your CSS or additional JavaScript files here.

• Makefile.options Configure your project here.

• pdldemo.conf.in. This file is a template for the configuration file for Ocsigen Server. You will rarely have to edit it yourself - it takes its variables from the Makefile.options. This way, the installation rules and the configuration files are synchronized with respect to the different folders.

• mobile The files needed by Cordova mobile apps

• Makefile This contains all rules necessary to build, test, and run your Eliom application. See below for the relevant targets.

• README.md

Makefile targets

Here's some help on how to work with this basic distillery project:

• Initialize, start, create, stop, delete a local db, or show status:

make db-init
make db-start
make db-create
make db-stop
make db-delete
make db-status

• Test your application by compiling it and running ocsigenserver locally

make test.byte (or test.opt)

• Compile it only

make all (or byte or opt)

• Deploy your project on your system

sudo make install (or install.byte or install.opt)

• Run the server on the deployed project

sudo make run.byte (or run.opt)

If WWWUSER in the Makefile.options is you, you don't need the sudo. If Eliom isn't installed globally, however, you need to re-export some environment variables to make this work:

sudo PATH=$PATH OCAMLPATH=$OCAMLPATH LD_LIBRARY_PATH=$LD_LIBRARY_PATH make run.byte/run.opt

• If you need a findlib package in your project, add it to the variables SERVER_PACKAGES and/or CLIENT_PACKAGES. The configuration file will be automatically updated.

Build the mobile applications

Prepare the mobile infrastructure.

For all mobile platforms:

Make sure you have a working NPM installation. The needed NPM packages (like Cordova) will be installed automatically.

Warning: NPM packages (and especially Cordova plugins) are very sensitive to version changes. You may have to change version numbers in mobile/config.xml.in if something goes wrong during app generation. You may also have problems with old versions of gradle or wrong versions of Android packages ...

** Be prepared! You're entering an unstable world! **

For Android:

• Install JDK 7 or newer (openjdk-7-jdk package in Debian/Ubuntu)
• Install Gradle (gradle package in Debian/Ubuntu)
• Download and untar the Android SDK (the smaller version without Android Studio suffices), rename it so that you have a $HOME/android-sdk-linux/tools folder.
• Using the Android package management interface (or sdkmanager), install latest versions of SDK Tools (tools), SDK Platform-tools (platform-tools), and SDK Build-tools (build_tools;XXX)
• Install recent Android API: SDK Platform (platforms;XXX).
• From Extras, enable the Android Support Repository and the Google Repository.
• For convenience, add the SDK directories platform-tools and tools in your $PATH

If you will test on an Android device, you don't need to do anything else.

If you want to emulate an Android device, you need to

• install qemu-kvm
• From the tools/android interface, install a system image (e.g., Intel x86 Atom_64) and configure an emulator: go to Tools -> Manage AVDs -> Device definition (for example choose Nexus 6 no skin)

You can install any Android API version you want, depending on the platform you want to target. By default, in ocsigen Start, the minimal version is Android API 15.

For iOS:

• Xcode installs all dependencies you need.

• Some iOS-specific code exists. You should check it out. For instance, looking carefully at the PROJECT_NAME.conf.in file is mandatory if you're building an iOS app.

For Windows:

Ocsigen Start uses cordova-hot-code-push-plugin to upload local files (like CSS and JavaScript files, images and logo) when the server code changes.

Unfortunately, this plugin is not yet available for Windows Phone. However, as ocsigen Start also builds the website part, an idea is to run the website into a WebView on Windows Phones.

Even if Cordova allows you to build Windows app, it doesn't authorize you to load an external URL without interaction with the user.

Another solution is to build an Hosted Web App. It makes it possible to create easily an application based on your website. You can also use Windows JavaScript API (no OCaml binding available for the moment) to get access to native components. You can create the APPX package (package format for Windows app) by using Manifold JS, even if you are on MacOS X or Linux.

If you are on Windows, you can use Visual Studio Community. The Visual Studio Community solution is recommended to test and debug. You can see all errors in the JavaScript console provided in Visual Studio.

Here a complete tutorial from the Windows blog for both versions (with Manifold JS and Visual Studio).

If you use the Manifold JS solution, you need to sign the APPX before installing it on a device.

Launching the mobile app

The following examples are described for Android but they are also available for iOS: you only need to replace android by ios.

• Launch an Ocsigen server serving your app:

make test.opt

In the following commands, if APP_REMOTE is yes, the mobile app will be created by getting all the necessary files (js, etc) from a server. This may be used to create a mobile app for an which has not been compiled locally. With APP_REMOTE=no, the local files will be used.

The remote server address is given in the variable APP_SERVER. Replace ${YOUR_SERVER} by ${YOUR_IP_ADDRESS}:8080 in the following commands if you want to test on your local machine.

• To run the application in the emulator, use:

make APP_SERVER=http://${YOUR_SERVER} APP_REMOTE=no emulate-android

The above command will attempt to launch your app in the Android emulator that you have configured previously. Depending on your setup, you may need to start the emulator before running the command.

To run the application on a connected device, use:

make APP_SERVER=http://${YOUR_SERVER} APP_REMOTE=no run-android

Notice that the APP_SERVER argument needs to point to your LAN or public address (e.g., 192.168.1.x), not to 127.0.0.1 (neither to localhost). The reason is that the address will be used by the Android emulator/device, inside which 127.0.0.1 has different meaning; it points to the Android host itself.

If you only wants to build the mobile application, you can use:

make APP_SERVER=http://${YOUR_SERVER} APP_REMOTE=no android

Before uploading on Google Play Store, check the variables in Makefile.options (MOBILE_APP_IP, version number, etc). You'll need to build a release version (default is debug version):

make APP_SERVER=http://${YOUR_SERVER} APP_REMOTE=no android-release

then sign it (see Android documentation).

If you want the application URL to include a path (http://${YOUR_SERVER}${PATH}), you need to provide an additional APP_PATH argument, e.g., APP_PATH=/foo. You need to include the leading /, but no trailing /. You also need to modify the pdldemo.conf.in with a <site> tag.

Note: if any of the mobile-related targets fails due to the inexistent node command, you may need to create a symlink from node to nodejs, e.g., as follows:

ln -s /usr/bin/nodejs /usr/local/bin/node

Update the mobile application.

The mobile app is updated automatically at launch time, every time the server has been updated. To do that, Ocsigen Start is using Cordova Hot Code Push.

In order to make it work, you MUST use the following command every time you update the server:

make APP_SERVER=http://${YOUR_SERVER} APP_REMOTE={yes|no} chcp

Use Makefile.local file.

You need to define APP_REMOTE and APP_SERVER each time you want to build the mobile application or to update it.

If you don't want to pass the variables APP_SERVER and APP_REMOTE every time, you can change the values of these variables in Makefile.local.example and rename this file to Makefile.local. This way, the variables APP_REMOTE and APP_SERVER are not mandatory when you build or update the mobile application. You can use:

make chcp
make run-android
make run-ios
...

This file is meant for rules and variables that are only relevant for local development and it must not be deployed or shared (by default, this file is ignored by Git).