GNU/Linux local install instructions about janet-lang.org HOT 13 OPEN

Here's my attempt at touching on some of the details. If I get things wrong, I hope others will point out and amend :)

Regarding JANET_PATH, the jpm man page has this to say:

   JANET_PATH
         The location to look for Janet libraries. This is the only envi‐
         ronment variable Janet needs to find native and source code mod‐
         ules.  If  no  JANET_PATH is set, Janet will look in the default
         location set at compile time, which can be determined with  (dyn
         :syspath)

  JANET_MODPATH
         The location that jpm will use to install libraries to. Defaults
         to JANET_PATH, but you could set this to a  different  directory
         if  you  want to. Doing so would let you import Janet modules on
         the normal system path (JANET_PATH or (dyn :syspath)),  but  in‐
         stall  to  a different directory. It is also a more reliable way
         to  install  This  variable  is  overwritten   by   the   --mod‐
         path=/some/path if it is provided.

So my reading is that JANET_PATH can be involved in where jpm installs libraries, but it isn't the only determining factor. Note also that if JANET_PATH is set, it's used for locating (as compared to installing) libraries.

Regarding where janet itself is installed, IIUC, one can decide that via specifying an appropriate value for PREFIX when invoking make (in case this was not known, IIUC this is a convention among a variety of programs that use make (not always followed for building other programs)).

For your situiation, my guess is that you might do something like this:

PREFIX=$HOME/opt/janet make && PREFIX=$HOME/opt/janet make install

That's pretty close to what I do typically (though I also happen to have my jpm-related bits live nearby).

FWIW, jpm has a show-paths subcommand. When I run that here, I get something like (it's edited to use $HOME):

$ jpm show-paths
binpath:    $HOME/janet/bin
modpath:    $HOME/janet/lib/janet
libpath:    $HOME/janet/lib
headerpath: $HOME/janet/include/janet
syspath:    $HOME/janet/lib/janet

I mention this part to give you some idea of what a system that seems to be running ok might be like -- I think I've seen other people do something similar. As to what the binpath, etc. mean, I think the jpm man page has a description for each one (in the form of --binpath, for example) -- except for syspath.

from janet-lang.org.

Quick description of the various paths:

• syspath: Where Janet will look for libraries before the current directory when using (import my-lib). can be overriden with $JANET_PATH, and if that is not provided, the default is set at build time (to look in /usr/local/lib/janet by default). jpm get this value from the janet binary. This is the only path that is actually native to the janet binary, not the jpm script.
• binpath: Where jpm built scripts and executables are installed.
• libpath: Where jpm will look for libjanet.so and libjanet.a when it needs them.
• headerpath: Where jpm will look for janet.h and janetconf.h
• modpath: Where jpm will install libraries when using jpm install. Defaults to the syspath, and in many cases you should only change the syspath. This lets you use jpm with one module tree to install packages to another module tree.

Besides syspath and modpath, the other path defaults are hardcoded into the jpm script itself. They can be overriden with both command line flags or environment variables, but during a system install it's best to just patch the script so that you need to set environment variables to get things working. There is a tool to do this that is called by make install.

from janet-lang.org.

Below is one take (corrections welcome :) ).

Looking at the "Glossary" section of: https://janet-lang.org/docs/jpm.html I see:

A project is a directory containing a project.janet file, which contains build recipes.

So your "git repo" idea seems consistent with this. (As a side note, I think it's possible for one to specify local directories as dependencies (IIRC, one writes a file:// URL or some such), though it may be that those local directories need to be git repositories.)

Note that in the section titled "Declaring a project" there is mention of declare-project. I think only one of these is supposed to be in project.janet.

The text continues:

Often, a project will correspond to a single git repository, and contain a single library.

So according to this it is possible for there to be only one library (module?) in a project. This might partly explain why one might hear statements that seem to conflate the two terms ("project" and "library") or use them interchanegeably in conversation.

Further bits of the text say:

However, a project's project.janet file can contain build recipes for as many libraries, native extensions, and executables as it wants.

Looking at the "Creating a module", "Creating a native module", and "Creating an executable" at: https://janet-lang.org/docs/jpm.html you'll likely come across:

• declare-source
• declare-native
• declatre-exeutable

So I think these correspond to the terms libraries, native extensions, and executables, respectively, in the quote above. So here it seems library == module, but I think it would be less confusing in one's thinking to avoid the term "library" when trying to point to something specific.

Regarding "package", the "Installing a module" section of: https://janet-lang.org/docs/modules.html says:

You can pass in a git repository URL to the install command, and jpm will install that package globally on your system.

If you are not using jpm, you can place the file path.janet from the repository in your current directory, and Janet will be able to import it as well. However, for more complicated packages or packages containing native C extensions, jpm will usually be much easier.

So going by this, I think package == project is a fair interpretation.

Regarding "module", https://janet-lang.org/docs/modules.html has the text:

A module is a collection of bindings and its associated environment. By default, modules correspond one-to-one with source files in Janet, although you may override this and structure modules however you like.

So it's a notion that has a default but it can be something else.

The "Importing a Module" section says:

To use a module, the best way is use the (import) macro, which looks for a module with the given name on your system and imports its symbols into the current environment, usually prefixed with the name of the module.

So this is consistent with an edited version of your statement "you import a module".

To summarize a bit, if you focus on these constructs:

• declare-project
• declare-source
• declare-native
• declare-executable

that might help to reduce confusion.

FWIW, I found examining (by installation and creating) specific projects helped me in developing my current mental model.

For reference, below are examples where one or more of declare-source, declare-native, and/or declate-executable are used:

Only one:

• https://github.com/janet-lang/path (declare-source)
• https://github.com/janet-lang/circlet (declare-native)
• https://github.com/pyrmont/documentarian (declare-executable)

More than one:

• https://github.com/andrewchambers/janet-sh (declare-native and declare-source)
• https://github.com/pepe/jff (declare-source and declare-executable)
• https://github.com/sogaiu/judge-gen (declare-executable x2)

from janet-lang.org.

For reference, there are some instructions here that might be relevant.

from janet-lang.org.

Thanks, @sogaiu . I plan to put some time in on this late next week.

from janet-lang.org.

This would be the instructions on https://janet-lang.org/docs/index.html under "Compiling and running from source" --> "macOS and Unix-like".

from janet-lang.org.

Thank you for the help. Sorry to take so long to get back to this issue, but I'm excited to sort this out.

So, I see three separate times to consider:

• When you install Janet (where you can use PREFIX is the usual way with the make command).
• When you install libraries/modules using jpm, and, I expect tied directly to this,
• when your program runs and needs to find and load libraries/modules at runtime.

It sounds like JANET_PATH is used for the latter two times.

As for terminology, my understanding is that:

• A module is typically a .janet file that you import.
• A "project" (? I think) is a git repo containing a project.janet file, and you can install a project using the jpm command.
• A "package" is just like in Python, I presume, where it's a namespace mechanism for where modules live: /my-proj/foo/bar/baz.janet would be the baz module in the foo/bar package...

Are those correct?

I'm somewhat confused by the jpm man page where, as sogaiu pastes:

JANET_MODPATH
    The location that jpm will use to install libraries to.

and @bakpakin 's comment above:

modpath: Where jpm will install libraries when using jpm install

What precisely is a janet "library"? (Or, how is a janet module different from a janet library?)

So, I didn't understand that when jpm installs things, it likes to have a similar selection of directories like what's found under /usr/local (it wants lib, bin, and include directories, for example). Why is a tree like that necessary? Does jpm install something else other than just .janet files? (Why would it need to install header files or binaries? My understanding is that janet is an interpreter that interprets .janet files...)

Thanks so much for helping me understand this! :)

from janet-lang.org.

Regarding terminology, looking at https://github.com/janet-lang/pkgs, I see that it uses "package" to mean the thing you install using jpm. Any clarity here would be appreciated. My best guess so far is that the terms are:

• you use jpm to install a package|library (a git repo with a project.janet file)
• you import a library|module

And "project" is just a more generic term.

from janet-lang.org.

Thank you. I think I'm gathering some more undertanding of this here.

To start with the very basics, I see that, for Janet projects, you cd into your project directory, and when you build artifacts (using jpm) they go into ./build, but then when you install them, jpm copies the build products into the tree under JANET_PATH.

It seems like I see and hear the term "library" when talking about native libraries, and "module" when talking about importable Janet source code modules. (Note: the wording in the jpm man page regarding JANET_PATH and JANET_MODPATH suggest the exact opposite of this, as opposed to the output of jpm show-paths which hints to me the opposite (and agrees with my guess at the start of this paragraph!)).

So, regarding a project's project.janet file, do I have the following correct? :

• declare-project: most every distributable Janet project will have this
• declare-source: (see also jpm show-paths --> modpath) used when your project provides a pure Janet source module
• declare-native: (see also jpm show-paths --> libpath) used when your project provides a native library (compiles C source into a native binary lib) (How is the Janet language or interpreter involved here?? What exactly is a native extension?)
• declare-executable: (see also jpm show-paths --> binpath) used when your project provides a standalone binary executable built from your Janet program wrapped up in and together with the Janet interpreter.

Please let me know if I have that correct. And if it is, if you think the docs could use a going-through to make sure the terms "library" (native extension) vs "module" (Janet source code module) are used consistently throughout.

from janet-lang.org.

declare-native: (see also jpm show-paths --> libpath) used when your project provides a native library (compiles C source into a native binary lib) (How is the Janet language or interpreter involved here?? What exactly is a native extension?)

This is incorrect iirc. libpath is where libjanet.a is located, libjanet.a/.so contains all the functions that comprise the janet interpreter. jpm needs to know where this is so it can link against it. Everything else is more or less correct.

I think module/library are used fairly interchangeably.

from janet-lang.org.

For:

declare-project: most every distributable Janet project will have this

I am trying to think of a case where it is possible to not have declare-project and for things to work, but my imagination is not helping.

Regarding the library and module distinction, I recommend examining and working with existing samples. Try building and installing (at least from what was listed above) -- then look for what files got installed where. In my case, this sort of experience helped to clarify my understanding.

In discussions where it seems unclear I would suggest asking for clarification.

I would be happier with more consistent usage of terms in the official docs and would be happy to review things (or suggest changes, make PRs, etc.). Pretty much avoiding library to point at anything specific seems to be working for me.

from janet-lang.org.

Ok, will experiment more! Thank you.

I realized one major point of confusion though! Oy! I had gotten used to installing a language that lived in its own directory. That is, for example, when you install $lang, you download its binary distribution, unpack it, and point your PATH to its very own ~/opt/${lang}/bin directory and you're all set (no actual "install" required beyond that). I'd forgotten that the probably more common case is that you download, unpack, build, then make install and it installs in an existing directory tree somewhere else (like /usr/local, which has all its bin, lib, include directories reading and waiting to be populated).

In addition to and aside from that, I was also conflating the "Janet install tree" with the jpm "module install tree", which (I think) is usually all the same tree: /usr/local ! But which can also be separate (I can install Janet locally into its own ~/opt/janet (where it then creates all its necessary bin, lib, include, share dirs)).

Again, I'll experiment more with setting JANET_PATH (and JANET_MODPATH) and trying to use jpm to install various kinds of build artifacts (and dependencies?) into ~/janet (as opposed to ~/opt/janet, where Janet itself is installed). Thanks, sogaiu.

Thanks, Andrew. I was at first confused about what you wrote about where libjanet.a/so is installed, but I think now I see that you were talking about the case where Janet itself and the jpm-installed libraries are all installed in the same tree (typically /usr/local).

from janet-lang.org.

Have not forgotten about this... Sorry for letting this wait so long.

from janet-lang.org.