✦ Stellar

Install Idris & Stellar

Stellar is an idris2 library, to use it, you will need to first install the toolchain from the idris2 ecosystem.

Step-by-step

The best way to use idris2 is with [pack][PACK]. But before you need to install Idris, for this we suggest you employ your Operating System’s package manager. Here are general instructions for Idris2.

Mac OS

with homebrew

brew install idris2

Archlinux

Idris is on aur

With Nix

nix-env -i idris2

Install pack

After installing Idris and its dependencies we can install Pack. It comes with an install script:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/stefan-hoeck/idris2-pack/main/install.bash)"

Once installed, I encourage you to install the following:

Install idris2-lsp

pack install idris2-lsp

install rlwrap

Use your package manager to install RLWrap. The repl does not support arrow keys.

Update your pack.toml

Pack should have created a pack.toml file in .config/pack, open it with your editor of choice, for example:

 vim ~/.config/pack/pack.toml
  • Add idris2-lsp to the whitelist: whitelist = [ "pack", "idris2-lsp" ]
  • Add idris2-lsp as a default app to download: apps = [ "idris2-lsp"]
  • Automatically use rlwrap in the repl: repl.rlwrap = true

Setup your project

To use stellar, you need to create a new Idris project, the fastest way is via pack --git-init new bin <name>.

This will create a directory with an empty skeleton project and initialise a .gitignore and git repository.

For example here is the folder created after running pack --git-init new bin stellar-example:

stellar-example
├── pack.toml
├── src
│   └── Main.idr
├── stellar-example.ipkg
└── test
    ├── src
    │   └── Main.idr
    └── test.ipkg

4 directories, 5 files

It is initialised as a git repository and has already configured a .gitignore.

Add Stellar as a Dependency

To add stellar as a dependency, open the .ipkg file, in the above example its full name is stellar-example.ipkg.

look for the -- depends = line, this line will list all the project’s dependencies. The two dashes -- indicate that the line is commented out. Replace the line by

depends = stellar-api, stellar-http-scheme

and save the file. Now if you compile the project with pack build, you should see pack pull stellar as a dependency.

[ info ] Found local config at /home/stellar-example/pack.toml
[ info ] Using package collection nightly-260525
[ info ] Installing libraries:
         - algdata
         - stellar-api
         - node
         - tyttp-adapter-node
         - continuation-monad
         - stellar-http-scheme
...

Implement Your First Program

Your project is all set up! You can now write your first program using Stellar, here is an example of an echo server that you can write in your src/Main.idr function.

module Main

import Stellar.API
import Stellar.HTTP

main : IO ()
main = http (localhost 8080) echo

There is a lot going on in this small program, you can learn more in the stellar-http section of the docs