Major: Directory structure

[iccir]

I feel like runtime.js and runtime.d.ts don't belong in src, as runtime.js is intended to be used by other projects in addition to ojc.

Likewise, esprima.js is derived from an external library. Perhaps it should live in an ext directory?

[IngwiePhoenix]

I’d put esprima.js into a lib/ folder, or ext-src/ runtime.js should go to the root, imho.

[iccir]

TypeScript, mocha, source-map, and others use lib for their deliverables, and then point main in package.json to one of the source files under lib. I always thought of lib as "a packaged and compiled version of src".

Is that not the case? Or are there different systems?

[IngwiePhoenix]

From my experience, there actually is a bit of a controversity between src/ and lib/

Basically, src/ reffers to the internal code, lib/ to externally accessible code. Think of public and private class properties.

But, lib/ is also used to provide a completely different kind of code. For example, some projects may have their main app in src/ and code that one can use to extend it in lib/

src/ a.cpp b.cpp ab.h main.cpp lib/ module.cpp, module.h

So, one would build from src/ - but, could extend the program from lib/ with something like a flag to make/configure/some-buildtool.

So its a so-so aproach; you basically can choose between:

• src/ : Private code
• lib/ : Public code

or

• src/ : Totally private code
• lib/ : Code that can be used to extend main code. Like extensions, etc.

Usually, in typical modules, the entry-script (index.js / main.js) is at the root. But some people move that into lib/ too and just refference it there.

[iccir]

Got it, thanks!

I like the idea of src being private, and lib being public (it's what babel appears to use, as well as the others that I mentioned. Esprima seems to use the root-level approach, although they are suppose to restructure the project eventually).

In that case, I'd probably want an api.js or something equivalent in lib which provides the Node API? For now, those would just use the private API in src. In the future, if I needed to use Babel or self-host with oj, I'd compile the contents of src into a lib deliverable and ship that?

[IngwiePhoenix]

api.js would basically act as a proxy into the private source code, to provide just what the user needs. the .compile() method, in the most common case.

Most projects that use NPM's build step to compile CoffeeScript and alike into plain javascript, use a dist/ folder.

src/app.coffee -> dist/app.coffee

You could also mimic the folder structure from root in dist/ to keep the public-private aproach, but having your source files compiled.

src/class1.oj -> dist/src/class1.js
lib/api.oj -> dist/lib/api.js

I would recommend to use NPM's build step to compile your sources, instead of actually loading your compiled sources into git. It only causes confusion if you publish a version and forget to update your build :)

{
    "scripts": {
        "build": "node src/build/run.js"
    }
}

// ... snip ... pseudo code.
ojc.compile({
    files: glob(path.join(__dirname, "../*.oj"))
    output: path.join(__dirname, "../../dist")
});

So when someone installs your stuff, ojc is ran, compiles the files into a usable distribution, and done.

[iccir]

I'm probably not going to self-host, but if I do, I'll definitely automate it with an NPM build step :)

api.js would have compile. I'm also investigating making parts of Compiler available as API (if Compiler objects stick around, it allows for faster incremental builds).

[IngwiePhoenix]

Okay, that sounds pretty cool. :)

[iccir]

I think this can be closed. The remaining issue was: "users should have a friendly way of getting runtime.js", and that is covered by: https://github.com/musictheory/oj/issues/121