Fluid

TODO

See also:

• Project Tracking - what we're actually working on right
• Darklang Community Discord
• Roadmap
• Contributor guide

See our guide to the repo for help browsing.

Contributing

TODO

Getting started

TODO

Install dependencies

We develop Dark within a docker container, so there is not a lot of setup. However, we do need to setup the host system in a few ways to support running scripts, and Docker.

OSX

To build and run the server you must have the following installed (and running):

• Homebrew for Mac
• Docker for Mac
• Bash 4 or later: brew install bash

Linux

Everything should just work on Linux, so long as you have docker installed and you are using bash 4 or later.

Windows

On Windows, you can run Dark in WSL2 (Windows Subsystem for Linux):

• You must be on at least Windows 10 Version 2004, and you must run WSL 2 (docker does not work in WSL 1)
• Follow the WSL 2 installation instructions
• Follow the Docker for WSL 2 installation instructions
• You need to clone the dark repo with the git core.autocrlf setting set to false. You can configure this by running git config --global core.autocrlf false. If you have already cloned dark, you will need to reclone it.
• This section of the guide is incomplete. Please create an issue if you find something doesn't work.

Building and running for the first time

Running the build script

Now that the pre-requisites are installed, we should be able to build the development container in Docker, which has the exact right versions of all the tools we use.

• If you're using VSCode, we run our build scripts in the VSCode devcontainer. See the VSCode instructions for instructions.
• Otherwise, simply run scripts/builder --compile --watch --test

These steps apply for all builds, VSCode or using scripts/builder:

• Wait until the terminal says "Initial compile succeeded" - this means the build server is ready. The builder script will sit open, waiting for file changes in order to recompile
• If you see "initial compile failed", it may be a memory issue. Sometimes trying again will work. If not, ensure you have Docker configured to provide 4GB or more of memory, then try again.
• Open your browser to http://darklang.localhost:9000/a/dark/, username "dark", password "what"
• Edit code normally - on each save to your filesystem, the app will be rebuilt and the browser will reload as necessary

Using Dark scripts

The scripts/ directory is full of scripts. They automatically execute in the dev container, even if they are run on the host (see scripts/devcontainer/_assert-in-container for how this works). Scripts starting with an underscore are primarily intended to be run by other scripts. Scripts without an underscore are usually intended to be called by a human, though they are often also called by other scripts as well.

Read the contributor docs

If you've gotten this far, you're now ready to contribute your first PR.

Advanced setup

• setting up dnsmasq
• setting up browser-reloading

Testing

Unit tests run when you specify --test to scripts/builder. You can run them as a once off using:

• scripts/run-client-tests

Running unix commands in the container

• scripts/run-in-docker bash

Accessing the local db

• scripts/run-in-docker psql -d devdb

Config files

Config files (config/) define all env vars that you can use in Dark code. All config vars must start with DARK_CONFIG. Changing a config variable in config/dev requires restaring the devcontanier.

Debugging the client

You can enable the FluidDebugger by mousing over the Gear in the left-sidebar. There is also "Enable debugger" which enables a legacy debugger that nobody uses and doesn't work well.

If you're using Chrome, enable Custom Formatters to see ReScript values in Chrome Dev Tools instead of their JS representation. From within Chrome Dev Tools, click "⠇", "Settings", "Preferences", "Enable Custom Formatters".

Other important docs

• Contributor docs
• Other ways to run the dev container
• Setting up your editor
• Running unit tests
• Dark unit tests
• If you're interviewing at Dark, read this

Less important docs

• Docs around running Dark in production
• Running the client against production (ngrok)
• Oplist serialization
• Intricacies of Bucklescript-tea
• Writing Stdlib docstrings
• Editing other BS libraries
• Add an account for yourself
• Using fuzzers to develop Dark
• Logging and telemetry
• Writing docstrings in the Dark Standard library