Providence : Getting Started with Providence

You do not need to install anything (but java) in order to start using providence. The project has builder plugins for maven and gradle, but if neither is used there is a binary code generator available here (check for the version of providence that you want to use).

Note that you always need to add a dependency to providence-core of the appropriate version for it to work.

Getting Providence CLI

See here for instructions on how to get morimekta.net CLI tools installed on your system. It has instructions for RedHat / YUM, Debian and Homebrew (for Mac):

http://dl.morimekta.net/

Developer Setup

In order to compile providence itself, you need the java 8 java and javac commands (I recommend openjdk8-jdk), and maven (3.5). Then check out [email protected]:morimekta/providence.git and build with:

mvn clean install -Plib

There is also a Makefile for updating pre-compiled providence and thrift files. These need make and docker installed to work, but is not required for most development.

Using Providence

Providence can currently be used through build steps in gradle and maven.

Maven

In maven the setup is simply to add a directory src/main/providence or src/test/providence where thrift files go, and add the providence-maven-plugin and the core library to the pom.xml file like this:

<project>
    <dependencies>
        <dependency>
            <groupId>net.morimekta.providence</groupId>
            <artifactId>providence-core</artifactId>
            <version>${providence.version}</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>net.morimekta.providence</groupId>
                <artifactId>providence-maven-plugin</artifactId>
                <version>${providence.version}</version>
                <extensions>true</extensions>
            </plugin>
        </plugins>
    </build>
</project>

And the providence generated files can be regenerated by:

mvn generate-sources
# or
mvn generate-test-sources

Now the generated providence files should be available in your project.

Gradle

When using gradle as build engine, you can use the providence-gradle-plugin, which can be added with the lines below. The thrift files goes to the same location as with maven: src/main/providence or src/test/providence.

var providence_version = '{providence version}'

plugins {
    id "net.morimekta.providence.gradle" version "${providence_version}" apply false
}

apply plugin: 'java'
apply plugin: 'net.morimekta.providence.gradle'

dependencies {
    compile "net.morimekta.providence:providence-core:${providence_version}"
}

And the providence generated files can be regenerated by:

./gradlew generateProvidence
# or
./gradlew generateTestProvidence

Note that as the providence-gradle-plugin requires the java plugin to work, it currently can not be used with android development, as the android plugin is incompatible with java.

Using with IDL tool

When using the Über IDL Tool, you need to override how the providence plugin refers to the directory containing the thrift files.

In maven it is specified with the includes parameter in the execution config.

<plugin>
    <groupId>net.morimekta.providence</groupId>
    <artifactId>providence-maven-plugin</artifactId>
    <extensions>true</extensions>
    <configuration>
        <input>
            <includes>
                <include>idl/**/*.thrift</include>
                <include>idl/**/*.providence</include>
            </includes>
        </input>
    </configuration>
</plugin>

In gradle it is done via the providence setup block:

providence {
    main {
        input = fileTree('idl') {
            include '**/*.thrift'
            include '**/*.providence'
        }
    }
}

Start Programming

Now make a thrift file in the src/main/providence folder, and start using it. You may need to refresh your IDE to catch the newly added generated source file folders.

Providence Customizable Serialization with Generated Models