Fluid: Language-integrated data provenance

Fluid is an experimental programming language which integrates a bidirectional dynamic analysis to connect outputs to data sources in a fine-grained way. Fluid is implemented in PureScript and runs in the browser.

Installation

Software required

• git
• Node.js >=18.0.0
• yarn >= 1.22

Additionally, for Windows users only:

• Ubuntu WSL

Building

• Clone the repository (for Windows users, do this under the Ubuntu WSL)
• Run ./script/setup/dev-setup.sh from the top-level directory
• yarn install to install Node dependencies
• yarn build

Use

The following assumes you have already successfully run yarn build (see above).

Running programs from the command line

Fluid examples in the dist/fluid/fluid can be evaluated from the command line as follows (from the top-level directory):

npx fluid evaluate -f <path>

Note that the path is relative and should not include the .fld extension, e.g. for the range.fld example:

% npx fluid evaluate -f example/range
((0, 0) : ((0, 1) : ((1, 0) : ((1, 1) : []))))
Success

Running websites locally (as part of Fluid development)

As an example, to build and run the website literate-execution:

• yarn build to ensure Fluid source code has been compiled (can be skipped on subsequent runs)
• yarn bundle-website literate-execution (can be skipped if the website being run is fluid-org)
• yarn serve literate-execution (you may be prompted to proceed; press y)
• Open a browser to the served URL (defaults to 127.0.0.1:8080)

Note: yarn bundle-serve is a convenient shorthand for yarn bundle-website followed by yarn serve

Testing

Running the tests from the command line

After building, tests can be run from the command line via yarn test-all

Running tests in browser

• As per command-line tests above, but run yarn test-browser, which opens a browser window.
• To observe the status of tests, click Debug in the browser window, and then open the JavaScript Console for your browser (e.g., via the Developer Tools).

Run Puppeteer tests for website X

• yarn bundle-website X
• yarn test-website X

Rebuild with puppeteerTests.headless set to false to run in browser.

Development via VS Code

The following are some notes on developing Fluid using VS Code.

• Avoid having PureScript installed globally

• Install the PureScript IDE extension

• In the PureScript IDE extension settings, select Add Npm Path

• For Windows users:

  • Launch VSCode through Ubuntu (WSL) terminal
  • Install WSL extension in VSCode