Update up_and_running.adoc

[behrica]

mention local in the cider-jack-in introduction

I think we should a bit more express that cider-jack-in works always for "local" situation and "often" for "remote" (but not always, even when setting the configurations CIDER has correctly).

[bbatsov]

I think the second "local" is kind of redundant here.

[bbatsov]

"often" for "remote" (but not always, even when setting the configurations CIDER has correctly).

Probably we should actually document what "often" means, as I find this a bit unclear.

In general it'd be nice to break the remote section into a part about editing files remote with TRAMP and a part about just using cider-connect to connect to a remote nREPL host. Given how different those use-cases are it's probably not a good idea to mix them in a single place.

[behrica]

I thought about this a lot and it is tricky to explain in simple words.
The issue is that cider-jack-in does two operations in one, namely "start a nREPL server" and "connect to a port".

It assumes a certain relation between the (TRAMP) connection to a file and the "host" + "port" under which the nREPL
connection should be available.

The first part nearly always goes well, so knowing the ssh name, CIDER can indeed just run "ssh host-name clojure ...."
(Eventhough I have seen failures on this as well, as clojure executable is not in PATH of remote host and TRAMP fails to find it)
But the assumption of which host and which port to connect to, might fail in several situations.

[behrica]

Not sure, how better to express "often".
CIDER makes several assumptions during the jack-in process with remote hosts, which all have a certain probability of being true,
but CIDER can hardly check them:

1. "often" the ssh host of the TRAMP session is the same as the ssh host to start clojure on
2. "often" the remote clojure can be started as ssh host-name clojure, but sometimes clojure is not in the PATH used by ssh / in the PATH used by TRAMP
3. "often" the host for cider-connect is the same as the two host names before
4. "often" the port of nREPL can be read from the local nrepl-port file

I think we should indeed re-organize the related docu into "start server" (for which we have now a new command cider-nrepl-start-server) and make a connection with cider-connect.

And finally position cider-jack-in as a short-cut for the "local situation".
(But it would be still confusing that cider-jack-in tries to work with and allows to configure a few common remote scenarios)

[bbatsov]

I have to admit I don't use TRAMP and I'm not a big fan of it, so I can't really offer much advise here. This feature was submitted to CIDER by contributors and I accepted it, because I know TRAMP is somewhat popular in the Emacs community.

For me CIDER was always mostly a tool for local development, but I guess the rise of containers in recent years changed the meaning of "local development". :-)

I think we should indeed re-organize the related docu into "start server" (for which we have now a new command cider-nrepl-start-server) and make a connection with cider-connect.

Generally, I've tried to follow what SLIME and similar tools were doing - start a server and connect to it by default (I assume some CIDER users have no idea what nREPL is for instance). That's why cider-jack-in is the command that's mentioned the most in the docs. Typically the people who'd prefer a more custom workflow, also have more knowledge of the tools and they won't mind reading a bit more documentation to achieve what they want.

Perhaps the "Up and Running" should be reduced to a "quickstart" type of page, and most of the content there should be reorganized in a different page dedicated to starting and connecting to nREPL instances?

[behrica]

Some Docker related tooling (devpod) even makes the notion of "remote" invisible.
I can have running CIDER in a local Docker container (which I would have usually called a variant of remote),
but devpod does it's magic, so that:

• my code is still local (and mounted into Docker), so I can edit it locally (without TRAMP)
• it automatically port forwards nREPL port to (localhost:12345)

CIDER jack-in would fail in this scenario as well, because it would think to launch nREPL "local" (as file names are local), which is wrong....

This was as well my "original" idea for this PR.
To point out that "cider-jack-in" is mainly made for "local nREPL, local files scenarios" and has some feature for support some remote / container scenarios. Additionally I "believe" that it could never auto-work for all remote / Docker scenarios as it cannot detect what the scenarios precisely is. (it would need to inspect the full network / ssh setup / file mounts of a given local machine to do so)

I think CIDER has overall the needed features for all scenarios, but cider-jack-in covers only a subset and can never cover all. So the question is on how to express this in the docu.

[behrica]

I re-started the PR and propose to add a general "important" tag the moment we introduce the jack in command, which mentions its limitation for some remote scenarios.