Table of Contents

• Table of Contents
• Introduction
  • What is Pragma?
  • Who is Pragma for?
  • Tell People About This
  • Documentation
• Install Pragma
  • Linux
  • macOS
  • Windows
• Getting Started
• Community & Support
• Contributing

Introduction

What is Pragma?

Pragma is a language for building beautiful and extensible GraphQL APIs in no time. Within a single file, you can define your data models and authorization rules (roles and permissions), and import serverless functions for data validation, transformation, authorization, or any custom logic. With a single command, Pragma generates a fully functional API, ready to be consumed from your front-end application.

Who is Pragma for?

Pragma is for developers who want to build, iterate, and ship as fast as possible and focus on user-facing features instead of dealing with resolvers, endpoints, migrations, authentication, authorization, scaling, queries, and all the headache that comes with building and maintaining an API.

Pragma is a perfect fit for startups. In fact, the original motivation behind it was testing new ideas in hours or days instead of weeks or months. It is designed to help you move quickly.

Pragma helps you focus on your users and primary business/domain logic, deliver a lot faster (10-100x faster than traditional frameworks), iterate and try new ideas with minimal technical cost.

Pragma is great for building internal tools too. You don't want to spend too much time building an internal tool, you just want it to work; Pragma is a great fit for such situations.

Pragma is for developers who want to materialize their ideas quickly, and share them with the world.

Pragma is for builders.

Tell People About This

Hyped? Tweet about this project and tell your followers how interesting this is.

You can also join our Discord server to meet other developers, get community support, and have fun!

Documentation

Visit the documentation to learn Pragma in a few minutes.

Install Pragma

Linux

Requirements

• Docker and Docker Compose

To make sure you have them and that they work, run:

docker run hello-world

docker-compose --help

If any of the above commands fail, make sure it works before proceeding with the installation of Pragma.

Installation

To install Pragma, run:

curl https://raw.githubusercontent.com/pragmalang/pragma/master/scripts/install-universal.sh | sh

The script will ask for root access, so make sure to enter your password when prompted.

If you're on Ubuntu/Debian, you can download the .deb package from releases.

Run Pragma

Once Pragma is downloaded and installed, you can see if it works by running the following command:

pragma help

macOS

Requirements

• Docker and Docker Compose
• Java

To make sure you have them and that they work, run:

docker run hello-world

docker-compose --help

java -version

If any of the above commands fail, make sure it works before proceeding with the installation of Pragma.

Note: When installing Java, make sure to use the macOS Installer. The macOS version of Pragma is the only one that doesn't come with a bundled Java runtime, due to the latest security features in macOS Catalina+. :::

Run Pragma

Once Pragma is downloaded and installed, you can see if it works by running the following command from the terminal:

pragma help

Windows

Requirements

• Docker and Docker Compose

To make sure you have them and that they work, run:

docker run hello-world

docker-compose --help

If any of the above commands fail, make sure it works before proceeding with the installation of Pragma.

Installation

First, we need to install the Pragma CLI:

• Download the latest MSI (.msi) installer from GitHub releases
• Run the installer and follow the installation wizard

Note: If Microsoft Defender tells you it prevented an unrecognized app from starting, click on "More info", then click on "Run anyway".

Run Pragma

Once Pragma is downloaded and installed, you can see if it works by running the following command from PowerShell:

pragma help

Getting Started

After Pragma has been successfully installed, visit this page of the documentation for a step-by-step tutorial on building a simple Todo application.

Community & Support

If you have any questions or feedback, you can join our Discord server or post to r/pragmalang. We would love to hear from you!

Contributing

Pragma is a Scala 2.13 project built using SBT. It's divided into three subprojects:

• core: where the domain abstractions and parsing logic is kept alongside any shared logic between other subprojects. All other subprojects depend on the core.
• daemon: where the serving and project management logic lives. It needs instances for Postgres and Openwhisk to be running; it's meant to be running alongside them in the background while using Pragma during development and in production.
• cli: where the communication with the daemon and the loading of user files is done.

It's highly recommended to be familiar with Cats and Cats Effect before starting to work on the daemon.

Setup

Pragma has been developed using VSCode with the Metals extension on Linux. For it all to work, it requires a JDK, Scala, SBT, and Ammonite for some scripts. Use this script to quickly install them:

curl -Lo cs https://git.io/coursier-cli-linux && chmod +x cs && ./cs setup

Docker and Docker Compose are also used for conveniently running Postgres and Openwhisk locally.

Testing

The recommended way to work on the daemon is to run it using SBT and run Postgres and Openwhisk from docker-compose.

To run Postgres and Openwhisk:

cd daemon/src/main/resources/ && docker-compose up

Make sure to run this before running sbt 'daemon/test'.

Running the daemon using sbt 'daemon/run' requires the following environment variables to be exported:

export DAEMON_HOSTNAME=localhost && \
export DAEMON_PORT=9584 && \
export DAEMON_PG_HOST='localhost' && \
export DAEMON_PG_PORT=5433 && \
export DAEMON_PG_DB_NAME='test' && \
export DAEMON_PG_USER='test'  && \
export DAEMON_WSK_API_URL='http://localhost:3233'  && \
export DAEMON_WSK_AUTH_TOKEN='23bc46b1-71f6-4ed5-8c54-816aa4f8c502:123zO3xZCLrMN6v2BKK1dXYFpXlPkccOFqm12CdAsMgRU4VrNZ9lyGVCGuMDGIwP'  && \
export DAEMON_PG_PASSWORD='test'  && \
export DAEMON_WSK_API_VERSION=1

You can run the daemon alongside Postgres and Openwhisk with:

# In the root of the project
docker-compose up

NOTE: If the docker containers cannot be started it's most likely because the port 5433 is already in use. Run docker ps and then run docker kill <postgres-containe-id> to kill the Postgres container to fix it.

Docker Build

Docker builds are performed using SBT Native Packager. To build the Pragma daemon Docker image:

sbt "daemon/docker:publishLocal"

CLI Packaging

NOTE: Generating the packages for each platform requires running the build on that very platform, in addition to some dependencies installed locally. See the requirements of each platform's plugin.

These packages should NOT require a local JDK installation, or have any dependencies since the Jlink plugin is used.

To build Linux packages:

sbt 'cli/debian:packageBin; cli/rpm:packageBin'

To build Windows installer (.msi):

sbt 'cli/windows:packageBin'

To build MacOS .dmg:

sbt 'cli/universal:packageOsxDmg'

Apache Bench benchmark

Run the ammonite script in test/benchmark:

amm PragmaBench.sc

Make sure the daemon is running before running the benchmark (run docker-compose up in the root of the project).

NOTE: Apache Bench must be installed:

sudo apt install apache2-utils

Documentation

The user documentation lives in website/docs and is built using Docusaurus 2. It's hosted on http://docs.pragmalang.com.