How to use gleam compile-package

[mjsir911]

Hi!

this is a continuation of #4986

mostly, just: how do I use this? there seems to be no documentation surrounding it and the builtin documentation is a little bit cryptic.

others looking for the same have started with the same questions as well: https://www.reddit.com/r/gleamlang/comments/1ebrq9s/does_gleam_have_a_core_compiler_eg_something_like/, even concluding the same compiler file name lmao

the only real reference to it on the blogs is https://gleam.run/news/v0.16-gleam-compiles-to-javascript/

specifically, the thing I'm confused about I think is the format of the libs dir. can't seem to get things working with that.

additionally, it looks like compile-package still needs a directory structure with gleam.toml and such. only the name field seems required rn. should probs be documented

I believe this is a bug that there is no surrounding or not discoverable documentation. I'm opening this discussion as a place for my immediate questions to be answered, but ideally this exists somewhere less user-content-focused.

[lpil]

Check out the --help document for that command, it'll show you what it can do.

It's a low level API that other build tools would use, similar to the compiler APIs you listed before, so there's not much motivation to document it heavily. It'll likely be used by almost no-one (I'm aware of two users user so far), and we don't want to accidentally give Gleam programmers the impression they should attempt to use it as they'll have a very poor experience.

[mjsir911]

I guess most of my confusion is the docs surrounding --lib. what is a "precompiled Gleam project"?

is build/packages that?:

build/packages/
├── gleam.lock
├── gleam_erlang
│   ├── LICENSE
│   ├── README.md
│   ├── gleam.toml
│   ├── include
│   │   ├── gleam@erlang@application_Failover.hrl
│   │   ├── gleam@erlang@application_Takeover.hrl
│   │   ├── gleam@erlang@process_Abnormal.hrl
│   │   ├── gleam@erlang@process_Cancelled.hrl
│   │   ├── gleam@erlang@process_ExitMessage.hrl
│   │   ├── gleam@erlang@process_NamedSubject.hrl
│   │   ├── gleam@erlang@process_PortDown.hrl
│   │   ├── gleam@erlang@process_ProcessDown.hrl
│   │   └── gleam@erlang@process_Subject.hrl
│   └── src
│       ├── gleam
│       │   └── erlang
│       │       ├── application.gleam
│       │       ├── atom.gleam
│       │       ├── charlist.gleam
│       │       ├── node.gleam
│       │       ├── port.gleam
│       │       ├── process.gleam
│       │       └── reference.gleam
│       ├── gleam@[email protected]
│       ├── gleam@[email protected]
│       ├── gleam@[email protected]
│       ├── gleam@[email protected]
│       ├── gleam@[email protected]
│       ├── gleam@[email protected]

[lpil]

No, it's a package your custom build tool has already compiled with gleam compile-package. You'll need to ensure all of a package's dependencies are compiled before it can be compiled.

[iocat]

I've been writing bazel gleam compiling rules, wonder if I can provide an example.

The exact lib directory will look like this for erlang target:

        lib_directory
        └── library_1
            ├── _gleam_artefacts
            │   ├── *.cache
            │   ├── *.cache_meta
            │   ├── *.cache_inline
            │   └── *.erl
            └── ebin
                └── *.beam

Where we'll need to pass the lib_directory to gleam compile-package.

Check: https://github.com/iocat/rules_gleam/blob/main/gleam/build.bzl#L104