User Feedback

[Person-93]

You asked for some feedback a while ago, not sure if this is what you're looking for or if this is a helpful format for it, if not, let me know and I'll be happy to adjust. This is not really an issue per se, it's just my experience going through it, I am happy to open issues for individual things if that'd be helpful.

Here's a little story, I was kind of bored so it might be a bit hyperbolic and silly but I hope it helps.

---

The Story

Adventure Begins

I cloned your github repo and the README says the only documentation is on the project website and is not versioned. How do I know if the documentation I am looking at is for the same version of the compiler that I am using? I do not, but I press on.

The Quick Start docs say to add `joelang/.bin` to my path. This does not seem like a good idea to me. Projects that want me to clone their repos to try using them in-tree should not be asking me to do that. I reluctantly add it, but only for the current shell session.

I navigate the the examples directory and go into the hello-world sub-directory. I see that there is a pre-compiled binary there. I find it odd that compiler artifacts are checked into the repo but I try to run it. Unsurprisingly, it does not work.

❯ ./main 
./main: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.34' not found (required by ./main)

It was compiled to use a version of libc not present on my computer.

Compile It

No mind, I can always just recompile it, right?

❯ joec main.joe
node:internal/modules/cjs/loader:1078
  throw err;
  ^

Error: Cannot find module '/home/person93/projects/josephzidell/joelang/examples/hello-world/_build/compile.js'
    at Module._resolveFilename (node:internal/modules/cjs/loader:1075:15)
    at Module._load (node:internal/modules/cjs/loader:920:27)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:81:12)
    at node:internal/main/run_main_module:23:47 {
  code: 'MODULE_NOT_FOUND',
  requireStack: []
}

Node.js v18.16.0

This error seems to have nothing to do with the example, so I try again with no input file:

❯ joec
node:internal/modules/cjs/loader:1078
  throw err;
  ^

Error: Cannot find module '/home/person93/projects/josephzidell/joelang/examples/hello-world/_build/compile.js'
    at Module._resolveFilename (node:internal/modules/cjs/loader:1075:15)
    at Module._load (node:internal/modules/cjs/loader:920:27)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:81:12)
    at node:internal/main/run_main_module:23:47 {
  code: 'MODULE_NOT_FOUND',
  requireStack: []
}

Node.js v18.16.0

As expected.

You want me to do what? Why?!

It seems I was expected to add `joelang/.bin` to my path despite only being able to run it if my current directory is the project root.

❯ cd ../..

❯ joec
No filename or input provided.

At the Root of It All

❯ joec examples/hello-world/
File examples/hello-world/ does not exist.

❯ joec examples/hello-world/main.joe
Stderr Error: /bin/sh: 1: llc: not found

Stderr Error: /bin/sh: 1: llc: not found

Stderr Error: gcc: error: /home/person93/projects/josephzidell/joelang/examples/hello-world/.build/main.o: No such file or directory
gcc: fatal error: no input files
compilation terminated.

Stderr Error: /home/person93/projects/josephzidell/joelang/examples/hello-world/main: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.34' not found (required by /home/person93/projects/josephzidell/joelang/examples/hello-world/main)

Hm.... I definitely have LLVM installed, I use it for other projects... I turn back to the docs.
The requirements are listed after the quick start usage.

This is Required

I find it really odd that I need to have both LLVM and GCC installed, but it should still work because I do.

❯ node -v
v18.16.0

❯ npm -v
9.5.1

❯ llc --version
bash: llc: command not found

❯ gcc --version
gcc (Debian 10.2.1-6) 10.2.1 20210110
Copyright (C) 2020 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

This is startling to say the least. However, I have a trick up my sleeve.

❯ alias llc=llc-15

❯ llc --version
Debian LLVM version 15.0.7
  Optimized build.
  Default target: x86_64-pc-linux-gnu
  Host CPU: skylake

  Registered Targets:
    aarch64    - AArch64 (little endian)
    aarch64_32 - AArch64 (little endian ILP32)
    aarch64_be - AArch64 (big endian)
    amdgcn     - AMD GCN GPUs
    arm        - ARM
    arm64      - ARM64 (little endian)
    arm64_32   - ARM64 (little endian ILP32)
    armeb      - ARM (big endian)
    avr        - Atmel AVR Microcontroller
    bpf        - BPF (host endian)
    bpfeb      - BPF (big endian)
    bpfel      - BPF (little endian)
    hexagon    - Hexagon
    lanai      - Lanai
    m68k       - Motorola 68000 family
    mips       - MIPS (32-bit big endian)
    mips64     - MIPS (64-bit big endian)
    mips64el   - MIPS (64-bit little endian)
    mipsel     - MIPS (32-bit little endian)
    msp430     - MSP430 [experimental]
    nvptx      - NVIDIA PTX 32-bit
    nvptx64    - NVIDIA PTX 64-bit
    ppc32      - PowerPC 32
    ppc32le    - PowerPC 32 LE
    ppc64      - PowerPC 64
    ppc64le    - PowerPC 64 LE
    r600       - AMD GPUs HD2XXX-HD6XXX
    riscv32    - 32-bit RISC-V
    riscv64    - 64-bit RISC-V
    sparc      - Sparc
    sparcel    - Sparc LE
    sparcv9    - Sparc V9
    systemz    - SystemZ
    thumb      - Thumb
    thumbeb    - Thumb (big endian)
    ve         - VE
    wasm32     - WebAssembly 32-bit
    wasm64     - WebAssembly 64-bit
    x86        - 32-bit X86: Pentium-Pro and above
    x86-64     - 64-bit X86: EM64T and AMD64
    xcore      - XCore

❯ joec examples/hello-world/main.joe 
Stderr Error: /bin/sh: 1: llc: not found

Stderr Error: /bin/sh: 1: llc: not found

Stderr Error: gcc: error: /home/person93/projects/josephzidell/joelang/examples/hello-world/.build/main.o: No such file or directory
gcc: fatal error: no input files
compilation terminated.

Stderr Error: /home/person93/projects/josephzidell/joelang/examples/hello-world/main: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.34' not found (required by /home/person93/projects/josephzidell/joelang/examples/hello-world/main)

That did not work. Whatever is running llc isn't even using bash. I don't know how it can be convinced to use llc-15 as a valid llc executable.

Conclusion

I am defeated. I will not be able to to compile or run any code written in joelang as things currently stand.

[josephzidell]

Thank you for your time spent trying as well as your time putting all this feedback together. I appreciate you bringing this to my attention. This is very helpful.

Addressing your points:

• Documentation versioning: Created Add version to the docs joelang.dev#1 to track
• llc issues and adding joelang/.bin to the path: Started Release binaries #31 to discuss this
• Versioning the example executables: apologies for the confusion. They have been removed
• node:internal/modules/cjs/loader:1078 error: Good catch as well. It should work now.
• No filename or input provided.: Created Add help to joec command #29 to track this
• joec examples/hello-world/: Created Allow to run joec against a dir #30 to track this
• Requirements being listed after the quick start usage: Should be better now

[Person-93]

llc issues and adding joelang/.bin to the path: Started #31 to discuss this

I think it's important to distinguish between release binaries and running the compiler during development.

During development, I'd expect to have to specify which llvm toolkit should be used as there may be more than one available and different versions of the compiler may depend on different versions of llvm. Trying different versions of llvm is likely part of the development process.

For a release binary, I'd expect the llvm version to be pinned and for it to look be able to look for the version that it expects or for the correct version to be bundled with the installation.

[Person-93]

joec examples/hello-world/: Created #30 to track this

I'm not sure this is a good idea. I thought it might be that way because each example was in its own directory, I did not mean it as a recommendation.

This seems like something that is out of scope for a compiler. If you look at c or c++ compilers, passing them a single file (i.e. main.c or main.cpp) will output an executable file creatively name a.out.

Things like build directories, build profiles, etc are handled by build tools. Having a build tool specifically for your language might be nice, but it's probably overkill at this point.

I'd recommend not having the compiler try to figure out where to put its outputs. If this hampers development, you can write a package script that takes one of the example names as an argument and does whatever is most convenient to be done during development of the compiler.

As a side bonus this lets you put all of your single file examples in single files instead of their own directories.

[josephzidell]

Thank you. The desired direction for Joelang includes:

1. Bundling LLVM with the installation. Ideally, the user's machine needs to have none of the prerequisites.
2. The ability to run on a directory containing a main.joe file. Also, as far the examples go, there will be examples with multiple files and subdirectories, so I'm keeping each in its own dir.

[Person-93]

1. Bundling LLVM with the installation. Ideally, the user's machine needs to have none of the prerequisites.

To clarify, does installation mean a packaged release, or even just cloning the repository?