Playing with Flix on Windows

This repository gathers Flix code examples coming from various websites.
It also includes several build scripts (Ant files, Bash scripts, batch files, Gradle scripts, Make scripts) for experimenting with Flix on a Windows machine.

☛ Read the document "Did You Know?" from the Flix documentation to know more about the Flix ecosystem.

Ada, Akka, C++, Dart, Deno, Docker, Golang, GraalVM, Haskell, Kafka, Kotlin, LLVM, Modula-2, Node.js, Rust, Scala 3, Spark, Spring, TruffleSqueak and WiX Toolset are other topics we are continuously monitoring.

Project dependencies

This project depends on the following external software for the Microsoft Windows platform:

Optionally one may also install the following software:

Apache Ant 1.10 (requires Java 8) (release notes)
Flix nightly builds ¹
mdBook 0.4 ² (changelog)
MSYS2 2024 (change log)
Scala 2.13 (release notes)
Temurin JDK Mission Control 8.3 ³ (release notes)
Visual Studio Code 1.87 (release notes)

☛ Installation policy
When possible we install software from a Zip archive rather than via a Windows installer. In our case we defined C:\opt\ as the installation directory for optional software tools (in reference to the /opt/ directory on Unix).

For instance our development environment looks as follows (March 2024) ⁴:

C:\opt\apache-ant\              ( 43 MB)
C:\opt\apache-maven\            ( 10 MB)
C:\opt\flix-0.45.0\             ( 37 MB)
C:\opt\Git\                     (367 MB)
C:\opt\gradle\                  (138 MB)
C:\opt\jdk-temurin-21.0.2_13\   (326 MB)
C:\opt\jmc\                     ( 99 MB)
C:\opt\mdBook\                  ( 10 MB)
C:\opt\msys64\                  (5.5 GB)
C:\opt\scala-2.13.13\           ( 24 MB)
C:\opt\VSCode\                  (341 MB)

Directory structure ▴

This project is organized as follows:

bin\
docs\
examples\{README.md, areas, arrays, channels, ..}
flix\     (Git submodule)
lutz-examples\{README.md, channels, datalog, etc.}
CONTRIBUTIONS.md
BUILD.md
DEPS.md
QUICKREF.md
README.md
RESOURCES.md
setenv.bat
UBUNTU_WSL.md

where

directory bin\ provides several utility batch files.
directory docs\ contains Flix related papers/articles.
directory examples\ contains Flix code examples (see README.md).
directory flix\ contains our fork of the flix/flix repository as a Github submodule.
directory lutz-examples\ contains Flix code examples from Lutz Hühnken's article (see README.md).
file CONTRIBUTIONS.md presents ongoing works and contributions to the Flix project.
file BUILD.md presents the Flix build.
file DEPS.md lists library dependencies of published Flix distributions.
file QUICKREF.md gathers Flix language features.
file README.md is the Markdown document for this page.
file RESOURCES.md gathers Flix related documents.
file setenv.bat is the batch script for setting up our environment.
file UBUNTU_WSL.md presents a Flix code examples in Ubuntu WSL.

Bash/Batch commands ▴

We distinguish different sets of batch commands:

setenv.bat – This batch command makes external tools such as git.exe and gradle.bat directly available from the Windows command prompt (see section Project dependencies).

> setenv help
Usage: setenv { <option> | <subcommand> }
 
  Options:
    -debug      print commands executed by this script
    -verbose    print progress messages
 
  Subcommands:
    help        print this help message

examples\*\build.bat – Code examples can be built/run/tested using the build.bat command.

 > build
 Usage: build { <option> | <subcommand> }
  
 Options:
   -debug      print commands executed by this script
   -nightly    use latest Flix nightly build if locally available
   -verbose    print progress messages
  
 Subcommands:
   clean       delete generated files
   compile     generate program executable
   help        print this help message
   run         execute the generated program "areas"
   test        run the unit tests

examples\*\build.gradle – Code examples can be built/run/tested using the gradle.bat build tool.

examples\*\build.sh – Code examples can be built/run/tested using the bash.exe scripting tool.

> sh build.sh help
Usage: build.sh { <option> | <subcommand> }
 
Options:
  -debug       print commands executed by this script
  -nightly     select latest Flix nightly build if locally available
  -verbose     print progress messages
 
Subcommands:
  clean        delete generated files
  compile      compile Scala/Flix source files
  decompile    decompile generated code with CFR
  help         print this help message
  run          execute Flix program "areas"
  test         run the unit tests

Usage examples ▴

`setenv.bat`

We execute command setenv.bat once to setup our development environment; it makes external tools such as git.exe, gradle.bat, make.exe and sh.exe directly available from the command prompt:

> setenv
Tool versions:
   java 21.0.2, javac 21.0.2, scalac 2.13.13, flix v0.45.0,
   gradle 8.6, make 3.81, mdbook v0.4.37, mvn 3.9.6,
   git 2.44.0.windows.1, diff 3.10, bash 5.2.26(1)-release

> where git gradle make sh
C:\opt\Git\bin\git.exe
C:\opt\Git\mingw64\bin\git.exe
C:\opt\gradle\bin\gradle
C:\opt\gradle\bin\gradle.bat
C:\opt\make-3.81\bin\make.exe
C:\opt\Git\bin\sh.exe
C:\opt\Git\usr\bin\sh.exe

Command setenv.bat with option -verbose displays additional information:

the download of the Flix nightly build to directory %FLIX_HOME% (if not yet done),
the tool paths (which may not contain the version suffix, i.e. C:\opt\Git\bin\git.exe in some installations),
the environment variables defined locally within this session,
and the path associations (i.e. F:\ in this case, but other drive names may be displayed as path associations are globally defined).

> setenv -verbose
Assign path C:\Users\michelou\workspace-perso\flix-examples to drive F:
Download file "flix-2024-03-14.jar" to directory "C:\opt\flix-0.45.0"

Tool versions:
   java 21.0.2, javac 21.0.2, scalac 2.13.13, flix v0.45.0,
   gradle 8.6, make 3.81, mdbook v0.4.37, mvn 3.9.6,
   git 2.44.0.windows.1, diff 3.10, bash 5.2.21(1)-release
Tool paths:
   C:\opt\jdk-temurin-21.0.2_13\bin\java.exe
   C:\opt\jdk-temurin-21.0.2_13\bin\javac.exe
   C:\opt\scala-2.13.13\bin\scalac.bat
   C:\opt\gradle\bin\gradle.bat
   C:\opt\make-3.81\bin\make.exe
   C:\opt\mdBook\mdbook.exe
   C:\opt\apache-maven\bin\mvn.cmd
   C:\opt\Git\bin\git.exe
   C:\opt\Git\usr\bin\diff.exe
Environment variables:
   "ANT_HOME=C:\opt\apache-ant"
   "FLIX_HOME=C:\opt\flix-0.45.0"
   "GIT_HOME=C:\opt\Git"
   "GRADLE_HOME=C:\opt\gradle"
   "JAVA_HOME=C:\opt\jdk-temurin-21.0.2_13"
   "MAKE_HOME=C:\opt\make-3.81"
   "MAVEN_HOME=C:\opt\apache-maven"
   "MDBOOK_HOME=C:\opt\mdBook"
   "SCALA_HOME=C:\opt\scala-2.13.13"
Path associations:
   F:\: => %USERPROFILE%\workspace-perso\flix-examples

Footnotes ▴

[1] Flix nightly builds ↩

Our installation directory %FLIX_HOME% looks as follows on March 14, 2024 :

> tree /a /f c:\opt\flix-0.45.0 | tail -n +3
C:\opt\flix-0.45.0
    flix-2024-02-14.jar
    flix.jar

Command build.bat in our Flix projects features the -nightly option to choose the latest Flix nightly build archive file locally available instead of the release version (archive file flix.jar above).

[2] mdBook ↩

We use mdbook.exe to work on our local copy of the online book "Programming Flix" generated from the GitHub project flix/book.

[3] JDK Mission Control ↩

Each vendor provides his own distribution of the JDK Mission Control tool, e.g. Adoptium JDK Mission Control (our choice), Zulu Mission Control, Liberica Mission Control or Oracle JDK Mission Control.

We use jmc.exe to investigate issues occuring during the build of our GitHub fork of the flix/flix repository.

> %JMC_HOME%\bin\jmc.exe -vm %JAVA_HOME%\bin

[4] Downloads ↩

In our case we downloaded the following installation files (see section 1):

apache-ant-1.10.14-bin.zip                         (  9 MB)
apache-maven-3.9.6-bin.zip                         ( 10 MB)
flix.jar                                           ( 39 MB)
flix-2024-03-14.jar                                ( 39 MB)
gradle-8.6-bin.zip                                 (103 MB)
mdbook-v0.4.37-x86_64-pc-windows-msvc.zip          (  4 MB)
msys2-x86_64-20240113.exe                          ( 94 MB)
OpenJDK21U-jdk_x64_windows_hotspot_21.0.2_13.zip   (191 MB)
PortableGit-2.44.0-64-bit.7z.exe                   ( 46 MB)
org.openjdk.jmc-8.3.0-win32.win32.x86_64.zip       ( 87 MB)
scala-2.13.13.zip                                  ( 22 MB)

mics/March 2024 ▲

michelou / flix-examples