Skip to content

Instantly share code, notes, and snippets.

@jdunkerley

jdunkerley/Enso Getting Started Guide.md

Created September 22, 2023 16:01
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save jdunkerley/e09df2fb3cee6e72c00612f074ad0a9b to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save jdunkerley/e09df2fb3cee6e72c00612f074ad0a9b to your computer and use it in GitHub Desktop.
Download ZIP
Notes on starting work on Enso code.
Raw
Enso Getting Started Guide.md

sbt Build Commands:

  • clean: flushes all the stuff and can be useful when getting new code.
  • runtime/clean: flushes just the engine libs bits (so quicker).
  • buildProjectManagerDistribution: builds the project manager server executable.
  • buildEngineDistribution: builds the engine server and libraries distribution executable.
  • buildStdLib...: builds the standard library can be All or a specific one. Tends to leave the index in a mess so often lose the dropdowns or CB.

Running Enso IDE:

  • Just run the executable it will launch a GUI and a Project Manager. Opening a project opens a Language Server. IDE Dashboard <---> Project Manager --launches-> Language Server <---> IDE Graph Editor
    • Execution happens in the language server.
    • IDE and L/S have parsers reading and parsing the code.
  • Can separate the IDE and Project Manager: --engine false will stop IDE running the P/M. Either on the installed (%AppData%\Local\Programs\enso\enso.exe) or the built one in dist (.\dist\ide\win-unpacked\Enso.exe). (./run ide build ends up here).
  • Project Manager is in .\built-distribution\enso-project-manager-0.0.0-dev-windows-amd64\enso\bin\project-manager.exe if built by sbt.
  • THe libraries used by the L/S are read from %AppData%\Local\enso\dist so if you sym link 0.0.0-dev to .\built-distribution\enso-engine-0.0.0-dev-windows-amd64\enso-0.0.0-dev\ within the repo will use the output of buildEngineDistribution.
  • You also need a 0.0.0-dev.yaml file in the %AppData%\Local\enso\editions.
  • The edition is set within the package.yaml of all projects. edition: 0.0.0-dev and prefer-local-libraries: true
  • ENSO_JVM_OPTS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005" - sets up the connection to allow Java debugging of the Language Server (connect up IntelliJ to it).

Running Enso CLI:

  • If you run .\built-distribution\enso-engine-0.0.0-dev-windows-amd64\enso-0.0.0-dev\bin\enso it will run Enso in CLI mode.
  • Command line args and environment variables to control it.
  • --run <Path> runs a project or an enso script (something with a main function).
  • --in-project <Path> specifies the project the script runs in (really useful for our unit tests).
  • --ir-caches just use it - basically speeds up Enso compilation by using intermediate representation which is saved in a cache.
  • --inspect runs Enso CLI in debug mode and gives a URL to connect a Chrome debugger to.
  • ENSO_TEST_JUNIT_DIR specifies where to write the JUnit XML files to if running tests.
  • JAVA_OPTS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005" - sets up the connection to allow Java debugging (connect up IntelliJ to it).
  • Utility enso.ps1 script to run CLI.

Project Structure:

  • app: IDE. Visualisation code is app/gui/view/graph-editor/src/builtin/visualization/java_script/
  • app/gui2: New TS Vue GUI.
  • distribution/lib: The Enso code of the standard libs.
  • engine: The built-in types and runtime. Java code for built-ins are here.
  • std-bits: The Java code of the standard libs.
  • test: The unit tests for the Enso standard libs.
  • tools: The only thing that comes up in here is the legal review. Only matters if you update or change a third party library.
  • Want to exclude dist, built-distribution and target from the IDE.

Enso Project Structure:

  • package.yaml: has the edition and can have lots of meta data stuff.
  • src: has the Enso code.
  • src\Main.enso: entry point for the project.
  • data: has the data files. (optional)
  • .enso: internal stuff but basically a localised git repo containing all changes.

Enso Script Structure:

  • Imports at the top.
    • import Standard.Base.Data.List.List imports the List type from the List module in the Data.List folder in the Standard.Base library.
    • import Standard.Base.Data.List imports the List module in the Data.List folder in the Standard.Base library. Use bits of it as List.<...>
    • Can alias as for example import Standard.Base.Data.List as List_Module then use List_Module.<...>
    • from Standard.Base.Data.List import all imports all the types and functions in module to the names space (not prefixed).
    • from Standard.Base.Data.List import List, List_Error imports specifics.
    • polyglot java import <JavaFullClassName> imports a Java class (supports as as well).
    • "Best practice" is to sort the imports alphabetically within each library.
    • project imports within the same project. Within a library should be used don't use the full name.
    • Main.enso in a library is where we choose what we to export (export similar to import). from Standard.Base import all brings in whatever is exported from Main.enso in Standard.Base.
  • main = is the entry point for the script.
  • No return statement, last value from a block is returned. Makes early exit harder.
  • Variables are immutable. I.e. a=123; a=456 is not allowed.
  • <| folds the block into the line above.
  • if <cond> then <true block> else <false block> have to have the if/then/else on one line. case <cond> of\n True-> <true block>\n False-> <false block>.
  • Instance vs static functions. First argument is self then an instance function.
  • Extension function: Text.substring self start end = is an extension function on Text type.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment