Remove usage of triple backtick because not supported by code.dlang.org
This commit is contained in:
BBasile
GitHub
parent
0b9cb6ac31
commit
b52fcdcee5
109
README.md
109
README.md
|
|
@ -14,6 +14,7 @@ command line. The server (dcd-server) is responsible for caching imported files,
|
|||
calculating autocomplete information, and sending it back to the client.
|
||||
|
||||
# Status
|
||||
|
||||
This program is reasonably stable. Please report problems on the Github issue
|
||||
tracker. Please be sure that you have read the documentation before filing an
|
||||
issue. (If you want to help your bug to get fixed faster, you can create a
|
||||
|
|
@ -42,53 +43,62 @@ the issue.)
|
|||
|
||||
# Setup
|
||||
### General
|
||||
|
||||
1. Install a recent D compiler. DCD is tested with DMD 2.068.2, DMD 2.069.0-rc2, and LDC 0.16 (Do not use DMD 2.068.1)
|
||||
1. Follow the directions listed below for Homebrew, Git + Make, or Dub, depending on how you would like to build DCD.
|
||||
1. Configure your text editor to call the dcd-client program. See the [wiki](https://github.com/dlang-community/DCD/wiki/IDEs-and-Editors-with-DCD-support) for information on configuring your specific editor.
|
||||
1. Start the dcd-server program before editing code. (Unless, of course, your editor's plugin handles this for you)
|
||||
|
||||
### Git + Make
|
||||
|
||||
1. Install a recent D compiler. DCD is tested with DMD 2.068.2, DMD 2.069.0-rc2, and LDC 0.16 (Do not use DMD 2.068.1)
|
||||
1. Run ```git submodule update --init --recursive``` after cloning this repository to grab the various dependencies.
|
||||
1. Run ```make``` to build the client and server. (Or run build.bat on Windows). ```make ldc``` and ```make gdc``` will use the LDC or GDC compilers. The resulting executable will be much faster.
|
||||
1. Run `git submodule update --init --recursive` after cloning this repository to grab the various dependencies.
|
||||
1. Run `make` to build the client and server. (Or run build.bat on Windows). `make ldc` and `make gdc` will use the LDC or GDC compilers. The resulting executable will be much faster.
|
||||
|
||||
### OS X w/ Homebrew
|
||||
1. ```brew install dcd```
|
||||
|
||||
1. `brew install dcd`
|
||||
|
||||
### Dub
|
||||
1. ```dub build --build=release --config=client```
|
||||
1. ```dub build --build=release --config=server```
|
||||
|
||||
1. `dub build --build=release --config=client`
|
||||
1. `dub build --build=release --config=server`
|
||||
|
||||
# Sockets
|
||||
## TCP
|
||||
|
||||
On Windows DCD will use TCP sockets to communicate between the client and server.
|
||||
DCD can use TCP sockets on other operating systems if the client and server use
|
||||
the `--tcp` or `--port` command-line switches.
|
||||
|
||||
## UNIX domain sockets
|
||||
|
||||
Operating systems that support UNIX domain sockets will use them by default.
|
||||
The path to the socket file can be overriden with the `--socketFile` option.
|
||||
These are the default paths:
|
||||
|
||||
#### OSX
|
||||
|
||||
The socket will be created at `/var/tmp/dcd-${UID}.socket`
|
||||
|
||||
#### Linux/BSD
|
||||
|
||||
The client and server will attempt to create the socket in the following locations:
|
||||
* `${XDG_RUNTIME_DIR}/dcd.socket`
|
||||
* `/tmp/dcd-${UID}.socket` if `XDG_RUNTIME_DIR` is not defined.
|
||||
|
||||
# Client
|
||||
|
||||
Because DCD is designed to be used from a text editor, this section is written
|
||||
primarily for plugin authors.
|
||||
|
||||
## Get autocomplete information
|
||||
|
||||
The primary use case of the client is to query the server for autocomplete information.
|
||||
To do this, provide the client with the file that the user is editing along with the
|
||||
cursor position (in bytes).
|
||||
|
||||
```dcd-client -c123 sourcefile.d```
|
||||
dcd-client -c123 sourcefile.d
|
||||
|
||||
This will cause the client to print a listing of completions to *stdout*.
|
||||
The client will print either a listing of function call tips, or a listing of of
|
||||
|
|
@ -98,13 +108,18 @@ a left parethesis.
|
|||
The file name is optional. If it is not specified, input will be read from *stdin*.
|
||||
|
||||
### Dot completion
|
||||
|
||||
When the first line of output is "identifiers", the editor should display a
|
||||
completion list.
|
||||
|
||||
#### Output format
|
||||
|
||||
A line containing the string "identifiers" followed by the completions that are
|
||||
available, one per line. Each line consists of the completion name followed by a
|
||||
tab character, followed by a completion kind
|
||||
|
||||
##### Completion kinds
|
||||
|
||||
* c - class name
|
||||
* i - interface name
|
||||
* s - struct name
|
||||
|
|
@ -124,6 +139,7 @@ tab character, followed by a completion kind
|
|||
* T - mixin template name
|
||||
|
||||
#### Example output
|
||||
|
||||
identifiers
|
||||
parts v
|
||||
name v
|
||||
|
|
@ -136,6 +152,7 @@ tab character, followed by a completion kind
|
|||
getPartByName f
|
||||
|
||||
#### Extended output mode
|
||||
|
||||
You can pass `--extended` to dcd-client to get more information. Output will now be
|
||||
escaped (newlines get escaped to `\n`, tabs get escaped to `\t`, backslash gets escaped to `\\`).
|
||||
|
||||
|
|
@ -153,6 +170,7 @@ a tab separated format:
|
|||
* documentation: escaped documentation string of this symbol
|
||||
|
||||
#### Example `--extended` output
|
||||
|
||||
identifiers
|
||||
libraryFunction f Tuple!long libraryFunction(string s, string s2) stdin 190 foobar
|
||||
libraryFunction f int* libraryFunction(string s) stdin 99 Hello\nWorld
|
||||
|
|
@ -160,35 +178,47 @@ a tab separated format:
|
|||
libreTypes g stdin 298
|
||||
|
||||
#### Note
|
||||
|
||||
DCD's output will start with "identifiers" when completing at a left paren
|
||||
character if the keywords *pragma*, *scope*, *__traits*, *extern*, or *version*
|
||||
were just before the paren.
|
||||
|
||||
### Parenthesis completion
|
||||
|
||||
When the first line of output is "calltips", the editor should display a function
|
||||
call tip.
|
||||
|
||||
##### Output format
|
||||
|
||||
A line containing the string "calltips", followed by zero or more lines, each
|
||||
containing a call tip for an overload of the given function.
|
||||
|
||||
##### Example output
|
||||
|
||||
calltips
|
||||
Symbol findSymbolInCurrentScope(size_t cursorPosition, string name)
|
||||
|
||||
## Doc comment display
|
||||
```dcd-client --doc -c 4298```
|
||||
|
||||
dcd-client --doc -c 4298
|
||||
|
||||
When run with the --doc or -d option, DCD will attempt to display documentation
|
||||
comments associated with the symbol at the cursor position. In the case of
|
||||
functions there can be more than one documentation comment associated with a
|
||||
symbol. One doc comment will be printed per line. Newlines within the doc
|
||||
comments will be replaced with "\n", and backslashes escaped as "\\".
|
||||
|
||||
#### Example output
|
||||
|
||||
An example doc comment\nParams: a = first param\n Returns: nothing
|
||||
An example doc comment\nParams: a = first param\n b = second param\n Returns: nothing
|
||||
|
||||
## Clear server's autocomplete cache
|
||||
```dcd-client --clearCache```
|
||||
|
||||
dcd-client --clearCache
|
||||
|
||||
## Add import search path
|
||||
|
||||
Import paths can be added to the server without restarting it. To accomplish
|
||||
this, run the client with the -I option:
|
||||
|
||||
|
|
@ -196,7 +226,8 @@ this, run the client with the -I option:
|
|||
|
||||
|
||||
## Find declaration of symbol at cursor
|
||||
```dcd-client --symbolLocation -c 123```
|
||||
|
||||
dcd-client --symbolLocation -c 123
|
||||
|
||||
The "--symbolLocation" or "-l" flags cause the client to instruct the server
|
||||
to return the path to the file and the byte offset of the declaration of the
|
||||
|
|
@ -218,32 +249,33 @@ symbol type, and the byte offset of the symbol separated by tab characters.
|
|||
|
||||
Search the server's cache for symbols named "toImpl". (Using echo to give an EOF
|
||||
in place of a file being edited.)
|
||||
```echo | dcd-client --search toImpl``
|
||||
|
||||
```
|
||||
/usr/include/dmd/phobos/std/conv.d f 48491
|
||||
/usr/include/dmd/phobos/std/conv.d f 47527
|
||||
/usr/include/dmd/phobos/std/conv.d f 47229
|
||||
/usr/include/dmd/phobos/std/conv.d f 40358
|
||||
/usr/include/dmd/phobos/std/conv.d f 38348
|
||||
/usr/include/dmd/phobos/std/conv.d f 35619
|
||||
/usr/include/dmd/phobos/std/conv.d f 32743
|
||||
/usr/include/dmd/phobos/std/conv.d f 22486
|
||||
/usr/include/dmd/phobos/std/conv.d f 16322
|
||||
/usr/include/dmd/phobos/std/conv.d f 14829
|
||||
/usr/include/dmd/phobos/std/conv.d f 14066
|
||||
/usr/include/dmd/phobos/std/conv.d f 13058
|
||||
/usr/include/dmd/phobos/std/conv.d f 12717
|
||||
/usr/include/dmd/phobos/std/conv.d f 9494
|
||||
```
|
||||
echo | dcd-client --search toImpl
|
||||
|
||||
/usr/include/dmd/phobos/std/conv.d f 48491
|
||||
/usr/include/dmd/phobos/std/conv.d f 47527
|
||||
/usr/include/dmd/phobos/std/conv.d f 47229
|
||||
/usr/include/dmd/phobos/std/conv.d f 40358
|
||||
/usr/include/dmd/phobos/std/conv.d f 38348
|
||||
/usr/include/dmd/phobos/std/conv.d f 35619
|
||||
/usr/include/dmd/phobos/std/conv.d f 32743
|
||||
/usr/include/dmd/phobos/std/conv.d f 22486
|
||||
/usr/include/dmd/phobos/std/conv.d f 16322
|
||||
/usr/include/dmd/phobos/std/conv.d f 14829
|
||||
/usr/include/dmd/phobos/std/conv.d f 14066
|
||||
/usr/include/dmd/phobos/std/conv.d f 13058
|
||||
/usr/include/dmd/phobos/std/conv.d f 12717
|
||||
/usr/include/dmd/phobos/std/conv.d f 9494
|
||||
|
||||
## Find the use of the symbol at the cursor
|
||||
```dcd-client --localUse -c 123```
|
||||
|
||||
dcd-client --localUse -c 123
|
||||
|
||||
The "--localUse" or "-u" flags cause the client to instruct the server
|
||||
to return all the uses, within the same module, of the symbol located at the given cursor position.
|
||||
|
||||
#### Output format
|
||||
|
||||
When uses exist, if the source symbol is an identifier (a type, a variable name, etc.)
|
||||
and if the symbol is not ambiguous then the first line contains the location of the symbol
|
||||
(a file name or literally _stdin_), a tab then the offset to the symbol declaration.
|
||||
|
|
@ -254,22 +286,24 @@ from the start of the file to the i-th use.
|
|||
Otherwise the client outputs _00000_ so that the length of the answer is guaranteed to be at least 5 bytes.
|
||||
|
||||
#### Example output
|
||||
```
|
||||
stdin 45
|
||||
26
|
||||
45
|
||||
133
|
||||
```
|
||||
|
||||
stdin 45
|
||||
26
|
||||
45
|
||||
133
|
||||
|
||||
|
||||
# Server
|
||||
|
||||
The server must be running for the DCD client to provide autocomplete information.
|
||||
In future versions the client may start the server if it is not running, but for
|
||||
now it must be started manually or (usually) by an editor plugin.
|
||||
|
||||
## Configuration Files
|
||||
The server will attempt to read the file ```${XDG_CONFIG_HOME}/dcd/dcd.conf```
|
||||
|
||||
The server will attempt to read the file `${XDG_CONFIG_HOME}/dcd/dcd.conf`
|
||||
(`~/.config/dcd/dcd.conf` if XDG_CONFIG_HOME is not set) on Posix systems, or
|
||||
```dcd.conf``` on Windows in the current working directory on startup.
|
||||
`dcd.conf` on Windows in the current working directory on startup.
|
||||
If it exists, each line of the file is interpreted as a path that should be
|
||||
searched when looking for module imports. Lines that start with the "#" character
|
||||
are ignored. Lines can contain environment variables which will be expanded
|
||||
|
|
@ -289,15 +323,18 @@ What you actually want is this:
|
|||
/usr/include/dmd/phobos
|
||||
|
||||
## Shut down the server
|
||||
|
||||
The server can be shut down by running the client with the `--shutdown` option:
|
||||
|
||||
dcd-client --shutdown
|
||||
|
||||
## Import directories
|
||||
|
||||
Import directories can be specified on the command line at startup:
|
||||
|
||||
dcd-server -I/home/user/code/one -I/home/user/code/two
|
||||
|
||||
## Port number
|
||||
The ```--port``` or ```-p``` option lets you specify the port number that the
|
||||
|
||||
The `--port` or `-p` option lets you specify the port number that the
|
||||
server will listen on. The default port is 9166.
|
||||
|
|
|
|||
Loading…
Reference in New Issue