Remove usage of triple backtick because not supported by code.dlang.org
This commit is contained in:
parent
0b9cb6ac31
commit
b52fcdcee5
73
README.md
73
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.
|
calculating autocomplete information, and sending it back to the client.
|
||||||
|
|
||||||
# Status
|
# Status
|
||||||
|
|
||||||
This program is reasonably stable. Please report problems on the Github issue
|
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
|
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
|
issue. (If you want to help your bug to get fixed faster, you can create a
|
||||||
|
@ -42,53 +43,62 @@ the issue.)
|
||||||
|
|
||||||
# Setup
|
# Setup
|
||||||
### General
|
### 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. 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. 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. 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)
|
1. Start the dcd-server program before editing code. (Unless, of course, your editor's plugin handles this for you)
|
||||||
|
|
||||||
### Git + Make
|
### 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. 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 `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 `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
|
### OS X w/ Homebrew
|
||||||
1. ```brew install dcd```
|
|
||||||
|
1. `brew install dcd`
|
||||||
|
|
||||||
### Dub
|
### 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
|
# Sockets
|
||||||
## TCP
|
## TCP
|
||||||
|
|
||||||
On Windows DCD will use TCP sockets to communicate between the client and server.
|
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
|
DCD can use TCP sockets on other operating systems if the client and server use
|
||||||
the `--tcp` or `--port` command-line switches.
|
the `--tcp` or `--port` command-line switches.
|
||||||
|
|
||||||
## UNIX domain sockets
|
## UNIX domain sockets
|
||||||
|
|
||||||
Operating systems that support UNIX domain sockets will use them by default.
|
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.
|
The path to the socket file can be overriden with the `--socketFile` option.
|
||||||
These are the default paths:
|
These are the default paths:
|
||||||
|
|
||||||
#### OSX
|
#### OSX
|
||||||
|
|
||||||
The socket will be created at `/var/tmp/dcd-${UID}.socket`
|
The socket will be created at `/var/tmp/dcd-${UID}.socket`
|
||||||
|
|
||||||
#### Linux/BSD
|
#### Linux/BSD
|
||||||
|
|
||||||
The client and server will attempt to create the socket in the following locations:
|
The client and server will attempt to create the socket in the following locations:
|
||||||
* `${XDG_RUNTIME_DIR}/dcd.socket`
|
* `${XDG_RUNTIME_DIR}/dcd.socket`
|
||||||
* `/tmp/dcd-${UID}.socket` if `XDG_RUNTIME_DIR` is not defined.
|
* `/tmp/dcd-${UID}.socket` if `XDG_RUNTIME_DIR` is not defined.
|
||||||
|
|
||||||
# Client
|
# Client
|
||||||
|
|
||||||
Because DCD is designed to be used from a text editor, this section is written
|
Because DCD is designed to be used from a text editor, this section is written
|
||||||
primarily for plugin authors.
|
primarily for plugin authors.
|
||||||
|
|
||||||
## Get autocomplete information
|
## Get autocomplete information
|
||||||
|
|
||||||
The primary use case of the client is to query the server for 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
|
To do this, provide the client with the file that the user is editing along with the
|
||||||
cursor position (in bytes).
|
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*.
|
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
|
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*.
|
The file name is optional. If it is not specified, input will be read from *stdin*.
|
||||||
|
|
||||||
### Dot completion
|
### Dot completion
|
||||||
|
|
||||||
When the first line of output is "identifiers", the editor should display a
|
When the first line of output is "identifiers", the editor should display a
|
||||||
completion list.
|
completion list.
|
||||||
|
|
||||||
#### Output format
|
#### Output format
|
||||||
|
|
||||||
A line containing the string "identifiers" followed by the completions that are
|
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
|
available, one per line. Each line consists of the completion name followed by a
|
||||||
tab character, followed by a completion kind
|
tab character, followed by a completion kind
|
||||||
|
|
||||||
##### Completion kinds
|
##### Completion kinds
|
||||||
|
|
||||||
* c - class name
|
* c - class name
|
||||||
* i - interface name
|
* i - interface name
|
||||||
* s - struct name
|
* s - struct name
|
||||||
|
@ -124,6 +139,7 @@ tab character, followed by a completion kind
|
||||||
* T - mixin template name
|
* T - mixin template name
|
||||||
|
|
||||||
#### Example output
|
#### Example output
|
||||||
|
|
||||||
identifiers
|
identifiers
|
||||||
parts v
|
parts v
|
||||||
name v
|
name v
|
||||||
|
@ -136,6 +152,7 @@ tab character, followed by a completion kind
|
||||||
getPartByName f
|
getPartByName f
|
||||||
|
|
||||||
#### Extended output mode
|
#### Extended output mode
|
||||||
|
|
||||||
You can pass `--extended` to dcd-client to get more information. Output will now be
|
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 `\\`).
|
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
|
* documentation: escaped documentation string of this symbol
|
||||||
|
|
||||||
#### Example `--extended` output
|
#### Example `--extended` output
|
||||||
|
|
||||||
identifiers
|
identifiers
|
||||||
libraryFunction f Tuple!long libraryFunction(string s, string s2) stdin 190 foobar
|
libraryFunction f Tuple!long libraryFunction(string s, string s2) stdin 190 foobar
|
||||||
libraryFunction f int* libraryFunction(string s) stdin 99 Hello\nWorld
|
libraryFunction f int* libraryFunction(string s) stdin 99 Hello\nWorld
|
||||||
|
@ -160,35 +178,47 @@ a tab separated format:
|
||||||
libreTypes g stdin 298
|
libreTypes g stdin 298
|
||||||
|
|
||||||
#### Note
|
#### Note
|
||||||
|
|
||||||
DCD's output will start with "identifiers" when completing at a left paren
|
DCD's output will start with "identifiers" when completing at a left paren
|
||||||
character if the keywords *pragma*, *scope*, *__traits*, *extern*, or *version*
|
character if the keywords *pragma*, *scope*, *__traits*, *extern*, or *version*
|
||||||
were just before the paren.
|
were just before the paren.
|
||||||
|
|
||||||
### Parenthesis completion
|
### Parenthesis completion
|
||||||
|
|
||||||
When the first line of output is "calltips", the editor should display a function
|
When the first line of output is "calltips", the editor should display a function
|
||||||
call tip.
|
call tip.
|
||||||
|
|
||||||
##### Output format
|
##### Output format
|
||||||
|
|
||||||
A line containing the string "calltips", followed by zero or more lines, each
|
A line containing the string "calltips", followed by zero or more lines, each
|
||||||
containing a call tip for an overload of the given function.
|
containing a call tip for an overload of the given function.
|
||||||
|
|
||||||
##### Example output
|
##### Example output
|
||||||
|
|
||||||
calltips
|
calltips
|
||||||
Symbol findSymbolInCurrentScope(size_t cursorPosition, string name)
|
Symbol findSymbolInCurrentScope(size_t cursorPosition, string name)
|
||||||
|
|
||||||
## Doc comment display
|
## 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
|
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
|
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
|
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
|
symbol. One doc comment will be printed per line. Newlines within the doc
|
||||||
comments will be replaced with "\n", and backslashes escaped as "\\".
|
comments will be replaced with "\n", and backslashes escaped as "\\".
|
||||||
|
|
||||||
#### Example output
|
#### Example output
|
||||||
|
|
||||||
An example doc comment\nParams: a = first param\n Returns: nothing
|
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
|
An example doc comment\nParams: a = first param\n b = second param\n Returns: nothing
|
||||||
|
|
||||||
## Clear server's autocomplete cache
|
## Clear server's autocomplete cache
|
||||||
```dcd-client --clearCache```
|
|
||||||
|
dcd-client --clearCache
|
||||||
|
|
||||||
## Add import search path
|
## Add import search path
|
||||||
|
|
||||||
Import paths can be added to the server without restarting it. To accomplish
|
Import paths can be added to the server without restarting it. To accomplish
|
||||||
this, run the client with the -I option:
|
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
|
## 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
|
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
|
to return the path to the file and the byte offset of the declaration of the
|
||||||
|
@ -218,9 +249,9 @@ 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
|
Search the server's cache for symbols named "toImpl". (Using echo to give an EOF
|
||||||
in place of a file being edited.)
|
in place of a file being edited.)
|
||||||
```echo | dcd-client --search toImpl``
|
|
||||||
|
|
||||||
```
|
echo | dcd-client --search toImpl
|
||||||
|
|
||||||
/usr/include/dmd/phobos/std/conv.d f 48491
|
/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 47527
|
||||||
/usr/include/dmd/phobos/std/conv.d f 47229
|
/usr/include/dmd/phobos/std/conv.d f 47229
|
||||||
|
@ -235,15 +266,16 @@ in place of a file being edited.)
|
||||||
/usr/include/dmd/phobos/std/conv.d f 13058
|
/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 12717
|
||||||
/usr/include/dmd/phobos/std/conv.d f 9494
|
/usr/include/dmd/phobos/std/conv.d f 9494
|
||||||
```
|
|
||||||
|
|
||||||
## Find the use of the symbol at the cursor
|
## 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
|
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.
|
to return all the uses, within the same module, of the symbol located at the given cursor position.
|
||||||
|
|
||||||
#### Output format
|
#### Output format
|
||||||
|
|
||||||
When uses exist, if the source symbol is an identifier (a type, a variable name, etc.)
|
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
|
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.
|
(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.
|
Otherwise the client outputs _00000_ so that the length of the answer is guaranteed to be at least 5 bytes.
|
||||||
|
|
||||||
#### Example output
|
#### Example output
|
||||||
```
|
|
||||||
stdin 45
|
stdin 45
|
||||||
26
|
26
|
||||||
45
|
45
|
||||||
133
|
133
|
||||||
```
|
|
||||||
|
|
||||||
# Server
|
# Server
|
||||||
|
|
||||||
The server must be running for the DCD client to provide autocomplete information.
|
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
|
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.
|
now it must be started manually or (usually) by an editor plugin.
|
||||||
|
|
||||||
## Configuration Files
|
## 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
|
(`~/.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
|
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
|
searched when looking for module imports. Lines that start with the "#" character
|
||||||
are ignored. Lines can contain environment variables which will be expanded
|
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
|
/usr/include/dmd/phobos
|
||||||
|
|
||||||
## Shut down the server
|
## Shut down the server
|
||||||
|
|
||||||
The server can be shut down by running the client with the `--shutdown` option:
|
The server can be shut down by running the client with the `--shutdown` option:
|
||||||
|
|
||||||
dcd-client --shutdown
|
dcd-client --shutdown
|
||||||
|
|
||||||
## Import directories
|
## Import directories
|
||||||
|
|
||||||
Import directories can be specified on the command line at startup:
|
Import directories can be specified on the command line at startup:
|
||||||
|
|
||||||
dcd-server -I/home/user/code/one -I/home/user/code/two
|
dcd-server -I/home/user/code/one -I/home/user/code/two
|
||||||
|
|
||||||
## Port number
|
## 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.
|
server will listen on. The default port is 9166.
|
||||||
|
|
Loading…
Reference in New Issue