Skip to content

Commit

Permalink
Add documentation on installation on Windows.
Browse files Browse the repository at this point in the history
  • Loading branch information
doublep committed Apr 25, 2021
1 parent c9f333e commit a04f52f
Showing 1 changed file with 49 additions and 23 deletions.
72 changes: 49 additions & 23 deletions README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,7 @@ Eldev features:
* You can use local dependencies, even those that don’t use Eldev
(though some restrictions do apply, of course). This is similar to
Cask linking, but with more flexibility.
* Runs on all major operating systems: Linux, macOS, Windows.
* Eldev is fast.

Drawbacks:
Expand All @@ -93,8 +94,9 @@ Drawbacks:

Eldev is not widely used, but as of April 2021 there are
{uri-search-github}[around 50 projects on GitHub] that include file
`Eldev`, so it is quite well tested in the wild. Additionally, Eldev
contains a fairly large regression test collection.
`Eldev`, so it is already quite well tested in the wild.
Additionally, Eldev contains a fairly large regression test
collection.

TIP: If you are using {uri-flycheck}[Flycheck], check out
{uri-flycheck-eldev}[flycheck-eldev] package. It provides integration
Expand Down Expand Up @@ -152,10 +154,10 @@ files `Eldev` in these projects are documented below.
Eldev runs on Emacs 24.4 and up. On earlier Emacs versions it will be
overly verbose, but this is rather an Emacs problem.

Linux, macOS or other POSIX-like system is currently required.
However, since there is only a small shell script that is really
OS-dependent, porting to other systems should not be difficult
(volunteers welcome).
Any “typical” OS — Linux, macOS, Windows or any POSIX-like system not
listed earlier — will do. Additionally, since there is only a small
shell script (`.bat` file for Windows) that is really OS-dependent,
porting to other systems should not be difficult, volunteers welcome.

Eldev intentionally has no dependencies, at least currently: otherwise
your project would also see them, which could in theory lead to some
Expand All @@ -168,6 +170,7 @@ There are several ways to install Eldev.
[discrete]
==== Bootstrapping from MELPA: if you have a catch-all directory for executables

* On Linux, macOS, etc.:
. From this directory (e.g. `~/bin`) execute:
+
--
Expand All @@ -177,12 +180,20 @@ You can even do this from `/usr/local/bin` provided you have the
necessary permissions.
--

* On Windows:
. From this directory (e.g. `%USERPROFILE%\bin`) execute:
+
--
> curl.exe -fsSL https://raw.github.com/doublep/eldev/master/bin/eldev.bat > eldev.bat
--

No further steps necessary — Eldev will bootstrap itself as needed on
first invocation.

[discrete]
==== Bootstrapping from MELPA: general case

* On Linux, macOS, etc.:
. Execute:
+
--
Expand All @@ -191,49 +202,64 @@ first invocation.
This will install `eldev` script to `~/.eldev/bin`.
--

. Add the directory to your `$PATH`; e.g. in `~/.profile` add this:
. Add the directory to your `PATH`; e.g. in `~/.profile` add this:
+
export PATH="$HOME/.eldev/bin:$PATH"
export PATH="$HOME/.eldev/bin:$PATH"

* On Windows:
. Execute:
+
--
> curl.exe -fsSL https://raw.github.com/doublep/eldev/master/webinstall/eldev.bat | cmd

This will install `eldev.bat` script to `%USERPROFILE%\.eldev\bin`.
--

. Add this directory to your `PATH`:
+
> reg add HKCU\Environment /v Path /d "%USERPROFILE%\.eldev\bin;%PATH%" /f

Afterwards Eldev will bootstrap itself as needed on first invocation.

TIP: `eldev` doesn’t _really_ need to be findable through `$PATH` — it
TIP: `eldev` doesn’t _really_ need to be findable through `PATH` — it
will work regardless. This is rather for your convenience, so that
you don’t need to type the full path again and again.


[discrete]
==== Installing from sources

. Clone the source tree from GitHub.

. In the cloned working directory execute:
. In the cloned working directory execute,
* on Linux, macOS, etc.:
+
--
$ ./install.sh DIRECTORY
+
* on Windows:
+
> install.bat DIRECTORY

Here `DIRECTORY` is the location of `eldev` executable should be put.
It should be in `$PATH` environment variable, or else you will need to
It should be in `PATH` environment variable, or else you will need to
specify full path each time you invoke Eldev. You probably have
sth. like `~/bin` in your `$PATH` already, which would be a good value
sth. like `~/bin` in your `PATH` already, which would be a good value
for `DIRECTORY`. You could even install in e.g. `/usr/local/bin` —
but make sure you have permissions first.
--

[discrete]
==== Mostly for developing Eldev itself

. Clone the source tree from GitHub.

. Set environment variable `$ELDEV_LOCAL` to the full path of the
. Set environment variable `ELDEV_LOCAL` to the full path of the
working directory.

. Make sure executable `eldev` is available. Either follow any of the
first way to install Eldev, or symlink/copy file `bin/eldev` from
the cloned directory to somewhere on your `$PATH`.
the cloned directory to somewhere on your `PATH`.

Now each time Eldev is executed, it will use the sources at
`$ELDEV_LOCAL`. You can even modify it and see how that affects Eldev
`ELDEV_LOCAL`. You can even modify it and see how that affects Eldev
immediately.

=== Upgrading Eldev
Expand Down Expand Up @@ -1525,7 +1551,7 @@ Emacs, it will not use dependencies or previous test results, but
rather install or recompute them from scratch.

Normally, Eldev uses command `emacs` that is supposed to be resolvable
through `$PATH` environment variable. However, you can always tell it
through `PATH` environment variable. However, you can always tell it
to use a different Emacs version by setting either `ELDEV_EMACS` or
just `EMACS` in the environment, e.g.:

Expand Down Expand Up @@ -1574,7 +1600,7 @@ version is to use {uri-setup-emacs}[`purcell/setup-emacs`] action
provides), it is likely unsuitable for GitHub workflows.

There is a short shell script that installs Eldev itself for use on
GitHub runners. Modifying `$PATH` there is a bit tricky, so you
GitHub runners. Modifying `PATH` there is a bit tricky, so you
probably should just go with the script, as demonstrated below.

A basic workflow file (you can e.g. name it
Expand Down Expand Up @@ -1664,7 +1690,7 @@ script:
==== nix-emacs-ci

A newer tool to install Emacs is {uri-nix-emacs}[nix-emacs-ci]. Using
it is easy: define environment variable `$EMACS_CI` with the desired
it is easy: define environment variable `EMACS_CI` with the desired
Emacs version and `curl` a single shell script — whether on Linux or
macOS. With one more line you can also install Eldev. It appears to
be slower than EVM, but for continuous integration that’s not terribly
Expand Down Expand Up @@ -1696,7 +1722,7 @@ be used to install Emacs on it. Some projects successfully use
{uri-docker}[Docker] images.

Regardless of how you install Emacs, adding Eldev is yet another
one-liner. It is handy to use, because propagating `$PATH`
one-liner. It is handy to use, because propagating `PATH`
modifications between different commands on CircleCI is somewhat
non-obvious. To use it, add the following lines in the relevant place
in file `.circleci/config.yml`:
Expand Down Expand Up @@ -2442,7 +2468,7 @@ A few environment variables can affect Eldev’s behavior.

Use given Emacs executable (also for any child processes). If not
specified, this defaults to just `emacs`, which is expected
somewhere in `$PATH`.
somewhere in `PATH`.

`ELDEV_LOCAL`::

Expand Down

0 comments on commit a04f52f

Please sign in to comment.