server: introduce --listen, deprecate $NVIM_LISTEN_ADDRESS

man/nvim.1

@@ -329,6 +329,9 @@ Implies
 .Fl -headless .
 .It Fl -headless
 Do not start a user interface.
+.Fl -listen .
+.It Fl -listen Ar address
+Start RPC server on this pipe or TCP socket.
 .It Fl h , -help
 Print usage information and exit.
 .It Fl v , -version

runtime/doc/deprecated.txt

@@ -22,6 +22,10 @@ Commands ~
 *:wv*
 *:wviminfo*		Deprecated alias to |:wshada| command.
 
+Environment Variables ~
+*$NVIM_LISTEN_ADDRESS*	Deprecated in favor of |--listen|.  If both are given,
+			$NVIM_LISTEN_ADDRESS is ignored.
+
 Events ~
 *EncodingChanged*	Never fired; 'encoding' is always "utf-8".
 *FileEncoding*		Never fired; equivalent to |EncodingChanged|.

runtime/doc/eval.txt

@@ -1788,11 +1788,9 @@ v:scrollstart	String describing the script or function that caused the
 		hit-enter prompt.
 
 					*v:servername* *servername-variable*
-					*$NVIM_LISTEN_ADDRESS*
-v:servername	Primary listen address of the current Nvim instance, the first
-		item returned by |serverlist()|.  Can be set by
-		|--listen| or |$NVIM_LISTEN_ADDRESS| on startup.
-		See also |serverstart()| and |serverstop()|.
+v:servername	Primary listen-address of the current Nvim instance, the first
+		item returned by |serverlist()|.  Can be set by |--listen| or
+		|$NVIM_LISTEN_ADDRESS| at startup. |serverstart()| |serverstop()|
 		Read-only.
 
 

runtime/doc/msgpack_rpc.txt

@@ -70,9 +70,8 @@ An rpc socket is automatically created with each instance. The socket
  location is stored in |v:servername|. By default this is a named pipe
 with an automatically generated address. See |XXX|.
 
-To make Nvim listen on a TCP/IP socket instead, set the
-   |$NVIM_LISTEN_ADDRESS| environment variable before starting Nvim: >
-        NVIM_LISTEN_ADDRESS=127.0.0.1:6666 nvim
+To make Nvim listen on a TCP/IP socket instead, specify |--listen|: >
+    nvim --listen 127.0.0.1:6666
 <Also, more sockets and named pipes can be listened on using |serverstart()|.
 
 Note that localhost TCP sockets are generally less secure than named pipes,

runtime/doc/starting.txt

@@ -355,6 +355,10 @@ argument.
                 instead.
 		See also |silent-mode|, which does start a (limited) UI.
 
+--listen {addr}						*--listen*
+                Start |RPC| server on socket or TCP address {addr}. Sets the
+                primary listen address |v:servername| to {addr}. |serverstart()|
+
 ==============================================================================
 2. Initialization				*initialization* *startup*
 

src/nvim/main.c

@@ -110,6 +110,8 @@ typedef struct {
   int literal;                          /* don't expand file names */
 #endif
   int diff_mode;                        /* start with 'diff' set */
+
+  char *listen_addr;                    // --listen {address}
 } mparm_T;
 
 /* Values for edit_type. */
@@ -150,7 +152,6 @@ void event_init(void)
   signal_init();
   // finish mspgack-rpc initialization
   channel_init();
-  server_init();
   terminal_init();
 }
 
@@ -241,9 +242,8 @@ int main(int argc, char **argv)
   char_u *cwd = NULL;     // current workding dir on startup
   time_init();
 
-  /* Many variables are in "params" so that we can pass them to invoked
-   * functions without a lot of arguments.  "argc" and "argv" are also
-   * copied, so that they can be changed. */
+  // Many variables are in `params` so that we can pass them around easily.
+  // `argc` and `argv` are also copied, so that they can be changed.
   init_params(&params, argc, argv);
 
   init_startuptime(&params);
@@ -254,11 +254,10 @@ int main(int argc, char **argv)
   check_and_set_isatty(&params);
 
   event_init();
-  /*
-   * Process the command line arguments.  File names are put in the global
-   * argument list "global_alist".
-   */
+  // Process the command line arguments.  File names are put in the global
+  // argument list "global_alist".
   command_line_scan(&params);
+  server_init(params.listen_addr);
 
   if (GARGCOUNT > 0) {
     fname = get_fname(&params, cwd);
@@ -819,6 +818,9 @@ static void command_line_scan(mparm_T *parmp)
             if (!channel_from_stdio(true, CALLBACK_READER_INIT, &err)) {
               abort();
             }
+          } else if (STRNICMP(argv[0] + argv_idx, "listen", 6) == 0) {
+            want_argument = true;
+            argv_idx += 6;
           } else if (STRNICMP(argv[0] + argv_idx, "literal", 7) == 0) {
 #if !defined(UNIX)
             parmp->literal = TRUE;
@@ -1016,15 +1018,12 @@ static void command_line_scan(mparm_T *parmp)
           mainerr(err_opt_unknown, argv[0]);
       }
 
-      /*
-       * Handle option arguments with argument.
-       */
+      // Handle option arguments with argument.
       if (want_argument) {
-        /*
-         * Check for garbage immediately after the option letter.
-         */
-        if (argv[0][argv_idx] != NUL)
+        // Check for garbage immediately after the option letter.
+        if (argv[0][argv_idx] != NUL) {
           mainerr(err_opt_garbage, argv[0]);
+        }
 
         --argc;
         if (argc < 1 && c != 'S')          /* -S has an optional argument */
@@ -1063,13 +1062,17 @@ static void command_line_scan(mparm_T *parmp)
             break;
 
           case '-':
-            if (argv[-1][2] == 'c') {
-              /* "--cmd {command}" execute command */
-              if (parmp->n_pre_commands >= MAX_ARG_CMDS)
+            if (strequal(argv[-1], "--cmd")) {
+              // "--cmd {command}" execute command
+              if (parmp->n_pre_commands >= MAX_ARG_CMDS) {
                 mainerr(err_extra_cmd, NULL);
+              }
               parmp->pre_commands[parmp->n_pre_commands++] = argv[0];
+            } else if (strequal(argv[-1], "--listen")) {
+              // "--listen {address}"
+              parmp->listen_addr = argv[0];
             }
-            /* "--startuptime <file>" already handled */
+            // "--startuptime <file>" already handled
             break;
 
           case 'q':               /* "-q {errorfile}" QuickFix mode */
@@ -1210,11 +1213,10 @@ static void init_params(mparm_T *paramp, int argc, char **argv)
   paramp->want_full_screen = true;
   paramp->use_debug_break_level = -1;
   paramp->window_count = -1;
+  paramp->listen_addr = NULL;
 }
 
-/*
- * Initialize global startuptime file if "--startuptime" passed as an argument.
- */
+/// Initialize global startuptime file if "--startuptime" passed as an argument.
 static void init_startuptime(mparm_T *paramp)
 {
   for (int i = 1; i < paramp->argc; i++) {
@@ -1943,6 +1945,7 @@ static void usage(void)
   mch_msg(_("  --api-info            Write msgpack-encoded API metadata to stdout\n"));
   mch_msg(_("  --embed               Use stdin/stdout as a msgpack-rpc channel\n"));
   mch_msg(_("  --headless            Don't start a user interface\n"));
+  mch_msg(_("  --listen <address>    Start RPC server on this socket or TCP address\n"));
 #if !defined(UNIX)
   mch_msg(_("  --literal             Don't expand wildcards\n"));
 #endif

src/nvim/msgpack_rpc/server.c

@@ -32,24 +32,26 @@ static garray_T watchers = GA_EMPTY_INIT_VALUE;
 #endif
 
 /// Initializes the module
-bool server_init(void)
+bool server_init(const char *listen_address)
 {
   ga_init(&watchers, sizeof(SocketWatcher *), 1);
 
   bool must_free = false;
-  const char *listen_address = os_getenv(LISTEN_ADDRESS_ENV_VAR);
   if (listen_address == NULL) {
-    must_free = true;
-    listen_address = server_address_new();
-  }
-
-  if (!listen_address) {
-    return false;
+    // Deprecated: $NVIM_LISTEN_ADDRESS
+    listen_address = os_getenv(LISTEN_ADDRESS_ENV_VAR);
+    if (listen_address == NULL) {
+      must_free = true;
+      listen_address = server_address_new();
+      if (listen_address == NULL) {
+        return false;
+      }
+    }
   }
 
   bool ok = (server_start(listen_address) == 0);
   if (must_free) {
-    xfree((char *) listen_address);
+    xfree((char *)listen_address);
   }
   return ok;
 }

test/functional/eval/server_spec.lua

@@ -1,14 +1,14 @@
-
 local helpers = require('test.functional.helpers')(after_each)
 local eq, neq, eval = helpers.eq, helpers.neq, helpers.eval
 local command = helpers.command
 local clear, funcs, meths = helpers.clear, helpers.funcs, helpers.meths
+local ok = helpers.ok
 local os_name = helpers.os_name
 
 local function clear_serverlist()
-    for _, server in pairs(funcs.serverlist()) do
-      funcs.serverstop(server)
-    end
+  for _, server in pairs(funcs.serverlist()) do
+    funcs.serverstop(server)
+  end
 end
 
 describe('server', function()
@@ -96,16 +96,12 @@ describe('server', function()
     funcs.serverstart('127.0.0.1:65536')  -- invalid port
     eq({}, funcs.serverlist())
   end)
-end)
 
-describe('serverlist()', function()
-  before_each(clear)
-
-  it('returns the list of servers', function()
+  it('serverlist() returns the list of servers', function()
     -- There should already be at least one server.
     local n = eval('len(serverlist())')
 
-    -- Add a few
+    -- Add some servers.
     local servs = (os_name() == 'windows'
       and { [[\\.\pipe\Xtest-pipe0934]], [[\\.\pipe\Xtest-pipe4324]] }
       or  { [[Xtest-pipe0934]], [[Xtest-pipe4324]] })
@@ -126,3 +122,25 @@ describe('serverlist()', function()
     eq(n, eval('len(serverlist())'))
   end)
 end)
+
+describe('startup --listen', function()
+  it('validates', function()
+    clear()
+
+    local cmd = { unpack(helpers.nvim_argv) }
+    table.insert(cmd, '--listen')
+    eq('nvim: Argument missing after: "--listen"',
+       string.match(funcs.system(cmd), '.-n"'))
+
+    cmd = { unpack(helpers.nvim_argv) }
+    table.insert(cmd, '--listen2')
+    eq('nvim: Garbage after option argument: "--listen2"',
+       string.match(funcs.system(cmd), '.-2"'))
+  end)
+
+  it('sets v:servername, overrides $NVIM_LISTEN_ADDRESS', function()
+    clear({ env={ NVIM_LISTEN_ADDRESS='Xtest-env-pipe' },
+            args={ '--listen', 'Xtest-listen-pipe' } })
+    eq('Xtest-listen-pipe', meths.get_vvar('servername'))
+  end)
+end)