forks
/
DCD
mirror of https://github.com/dlang-community/DCD.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Remove usage of triple backtick because not supported by code.dlang.org

This commit is contained in:
BBasile 2018-04-24 07:15:18 +02:00 committed by GitHub
parent 0b9cb6ac31
commit b52fcdcee5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 73 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

109
README.md
View File

@ -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,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 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 47527 /usr/include/dmd/phobos/std/conv.d f 48491
/usr/include/dmd/phobos/std/conv.d f 47229 /usr/include/dmd/phobos/std/conv.d f 47527
/usr/include/dmd/phobos/std/conv.d f 40358 /usr/include/dmd/phobos/std/conv.d f 47229
/usr/include/dmd/phobos/std/conv.d f 38348 /usr/include/dmd/phobos/std/conv.d f 40358
/usr/include/dmd/phobos/std/conv.d f 35619 /usr/include/dmd/phobos/std/conv.d f 38348
/usr/include/dmd/phobos/std/conv.d f 32743 /usr/include/dmd/phobos/std/conv.d f 35619
/usr/include/dmd/phobos/std/conv.d f 22486 /usr/include/dmd/phobos/std/conv.d f 32743
/usr/include/dmd/phobos/std/conv.d f 16322 /usr/include/dmd/phobos/std/conv.d f 22486
/usr/include/dmd/phobos/std/conv.d f 14829 /usr/include/dmd/phobos/std/conv.d f 16322
/usr/include/dmd/phobos/std/conv.d f 14066 /usr/include/dmd/phobos/std/conv.d f 14829
/usr/include/dmd/phobos/std/conv.d f 13058 /usr/include/dmd/phobos/std/conv.d f 14066
/usr/include/dmd/phobos/std/conv.d f 12717 /usr/include/dmd/phobos/std/conv.d f 13058
/usr/include/dmd/phobos/std/conv.d f 9494 /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 ## 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.