chore: improve plain releases for local builds

.github/workflows/ci.yml

@@ -172,7 +172,7 @@ jobs:
             ${{ runner.os }}-mix-${{ matrix.elixir }}-${{ matrix.otp }}-
 
       - name: Build and release
-        run: just release-local
+        run: just burrito-local
 
   prep-matrix:
     runs-on: ubuntu-latest

.github/workflows/nightly.yml

@@ -26,7 +26,7 @@ jobs:
       - run: just deps engine
       - name: Set release version to latest rev
         run: sed -i "$ s/$/-$(git rev-parse --short HEAD)/" version.txt
-      - run: just release-all
+      - run: just burrito
         env:
           MIX_ENV: prod
       - name: Create Checksum

.github/workflows/release.yml

@@ -47,7 +47,7 @@ jobs:
         with:
           version: "0.15.2"
       - uses: actions/checkout@v6
-      - run: just release-all
+      - run: just burrito
         env:
           MIX_ENV: prod
       - name: Create Checksum

README.md

@@ -23,17 +23,36 @@ Then point your editor to the downloaded binary.
 
 ### Building from source
 
-To build Expert from source, you need Zig `0.15.2` installed on your system. Later versions will not work.
+Expert can be built in two ways: building a regular release for your own system(a "plain" release), or building
+a "burrito" release that works on multiple systems.
 
-Then you can run the following command or follow the instructions in the [Installation Instructions](pages/installation.md):
+To build Expert for your system, run the following command:
 
 ```sh
-just release-local
+just release
+```
+
+You can then point your editor to the `start_expert` executable in the generated release.
+You can also run `start_expert --help` to see available options.
+
+> [!IMPORTANT]
+>
+> If your editor doesn't do it automatically, make sure to pass the `--stdio` flag to Expert.
+
+To build Expert using burrito, you need Zig `0.15.2` installed on your system.
+Later versions will not work.
+
+Then you can run the following command:
+
+```sh
+just burrito-local
 ```
 
 This will build the Expert binary and place it in the `apps/expert/burrito_out` directory. You can then point your
 editor to this binary.
 
+You can find more information in the [Installation Instructions](pages/installation.md).
+
 ## Sponsorship
 
 Thank you to our corporate sponsors! Expert is currently in alpha and [we have organized all future work, including the first release, as milestones](https://github.com/elixir-lang/expert/milestones). If you'd like to start sponsoring the project, please read more below.

apps/expert/lib/expert/release.ex

@@ -59,4 +59,41 @@ defmodule Expert.Release do
 
     release
   end
+
+  def plain_assemble(release) do
+    executable = if windows?(), do: "start_expert.bat", else: "start_expert"
+    executable_path = Path.join([release.path, "bin", executable])
+
+    # Make the executable script runnable
+    File.chmod!(executable_path, 0o755)
+
+    if release.options[:quiet] do
+      release
+    else
+      Mix.shell().info("""
+
+      #{IO.ANSI.bright()}✨ Expert build created at:#{IO.ANSI.reset()} #{release.path}
+
+      To use it, point your editor LSP configuration to:
+
+          #{executable_path} --stdio
+
+      You can also run Expert in TCP mode by passing the `--port PORT` argument:
+
+          #{executable_path} --port 9000
+
+      To get a list of all available command line options, run:
+
+          #{executable_path} --help
+      """)
+
+      # Silence the release "announce" message
+      new_opts = Keyword.put(release.options, :quiet, true)
+      %{release | options: new_opts}
+    end
+  end
+
+  def windows? do
+    :os.type() |> elem(0) == :win32
+  end
 end

apps/expert/mix.exs

@@ -63,7 +63,7 @@ defmodule Expert.MixProject do
       plain: [
         strip_beams: false,
         cookie: "expert",
-        steps: release_steps()
+        steps: release_steps() ++ [&Expert.Release.plain_assemble/1]
       ]
     ]
   end

apps/expert/rel/overlays/bin/start_expert

@@ -0,0 +1,4 @@
+#!/bin/sh
+
+cd -P -- "$(dirname -- "$0")"
+exec ./plain eval "System.no_halt(true); Application.ensure_all_started(:xp_expert)" "$@"

apps/expert/rel/overlays/bin/start_expert.bat

@@ -0,0 +1,5 @@
+@echo off
+
+cd /d "%~dp0"
+.\plain.bat eval "System.no_halt(true); Application.ensure_all_started(:xp_expert)" --stdio
+

justfile

@@ -65,9 +65,9 @@ lint *project="all":
   just mix {{ project }} credo
   just mix {{ project }} dialyzer
 
-[doc('Build a release for the local system')]
+[doc('Build a burrito release for the local system')]
 [unix]
-release-local: (deps "engine") (deps "expert")
+burrito-local: (deps "engine") (deps "expert")
   #!/usr/bin/env bash
   cd apps/expert
 
@@ -80,21 +80,21 @@ release-local: (deps "engine") (deps "expert")
   MIX_ENV={{ env('MIX_ENV', 'prod')}} EXPERT_RELEASE_MODE=burrito BURRITO_TARGET="{{ local_target }}" mix release --overwrite
 
 [windows]
-release-local: (deps "engine") (deps "expert")
+burrito-local: (deps "engine") (deps "expert")
     # idk actually how to set env vars like this on windows, might crash
     EXPERT_RELEASE_MODE=burrito BURRITO_TARGET="windows_amd64" MIX_ENV={{ env('MIX_ENV', 'prod')}} mix release --overwrite
 
 [doc('Build releases for all target platforms')]
-release-all: (deps "engine") (deps "expert")
+burrito: (deps "engine") (deps "expert")
     #!/usr/bin/env bash
     cd apps/expert
 
     set -euxo pipefail
 
     EXPERT_RELEASE_MODE=burrito MIX_ENV={{ env('MIX_ENV', 'prod')}} mix release --overwrite
 
-[doc('Build a plain release without burrito')]
-release-plain: (deps "engine") (deps "expert")
+[doc('Build a plain release for the local system')]
+release: (deps "engine") (deps "expert")
     #!/usr/bin/env bash
     cd apps/expert
     MIX_ENV={{ env('MIX_ENV', 'prod')}} mix release plain --overwrite
@@ -105,7 +105,7 @@ compile-ci-matrix:
 
 [doc('Build and install binary locally')]
 [unix]
-install: release-local
+install: burrito-local
   #!/usr/bin/env bash
   set -euxo pipefail
 
@@ -116,4 +116,5 @@ install: release-local
 clean-engine:
   elixir -e ':filename.basedir(:user_data, "Expert") |> File.rm_rf!() |> IO.inspect()'
 
-default: release-local
+default: burrito-local
+

pages/development.md

@@ -8,18 +8,14 @@ required prerequisites.
 To build Expert, run:
 
 ```sh
-MIX_ENV=dev just release-local
+just release
 ```
 
->[!IMPORTANT]
-> We set `MIX_ENV=dev` to disable Burrito's caching mechanisms. This provides a
-> smoother development experience but expect server load times to be slightly
-> longer.
-
-You may point your editor's LSP configuration to path provided by Burrito, eg:
+You may point your editor's LSP configuration to the `start_expert` executable
+in the generated release:
 
 ```sh
-<your-repo>/apps/expert/burrito_out/expert_linux_amd64
+<your-repo>/apps/expert/_build/prod/rel/plain/bin/start_expert --stdio
 ```
 
 ## Logging

pages/installation.md

@@ -12,6 +12,7 @@ Caveats with the following versions of Elixir and Erlang are documented below:
 
 | Elixir   | Version Range  | Notes    |
 | -------- | -------------- | -------- |
+| 1.19     | `>= 1.19.0`    |          |
 | 1.18     | `>= 1.18.0`    |          |
 | 1.17     | `>= 1.17.0`    |          |
 | 1.16     | `>= 1.16.0`    |          |
@@ -53,9 +54,21 @@ just deps expert
 ...and build the project
 
 ```shell
-just release-local
+just burrito-local
 ```
 
+> ![NOTE]
+> If you want to skip burrito and build Expert only for your own system, you can
+> build a "plain" release instead by running:
+>
+> ```shell
+> just release
+> ```
+>
+> You can then find the generated `start_expert` executable in the
+> generated release directory. For the next steps, point your editor to
+> this executable instead.
+
 If things complete successfully, you will then have a release in your
 `apps/expert/burrito_out` directory. If you see errors, please file a
 bug.