mirror of https://gitlab.com/basile.b/dexed.git
829 lines
53 KiB
Plaintext
829 lines
53 KiB
Plaintext
Welcome to the Coedit Wiki, the documentation source for the small Windows & Linux IDE for the D programming language.
|
|
|
|
 
|
|
|
|
# Detailed setup procedure
|
|
|
|
There are four ways to get the program, from the simplest to the most complex:
|
|
* download and run the setup program build for each release.
|
|
* download and extract the binaries build for each release.
|
|
* build the program from the sources.
|
|
* download and install the official package for a linux distribution.
|
|
|
|
In all the cases, the _DMD_ D2 compiler must setup and its location has to match to one of the directory of the PATH environment variable.
|
|
If it's not already installed, [download](http://dlang.org/download.html) and setup DMD2 for your platform.
|
|
The latest Coedit version requires at least DMD 2.066.
|
|
|
|
## Setup program
|
|
|
|
* Go to [the release page](https://github.com/BBasile/Coedit/releases),
|
|
* Choose the zipped setup for your platform (at the bottom of a release log, the buttons labeled `coedit.<version>.<platform>.setup.zip`).
|
|
* The content must be extracted and executed:
|
|
* note that the option `--nodcd` can be typed to skip the installation of the completion daemon.
|
|
* Linux, all users, in a console `cd` to the file location and type `sudo ./coedit.<version>.<platform>.setup`.
|
|
* Linux, only you, in a console `cd` to the file location and type: `./coedit.<version>.<platform>.setup`.
|
|
* Windows, optional, it may be necessary to deactivate your anti-virus software. Norton AV has been reported for detecting a potential threat in his heuristic module and Avast AV not to allow the setup at all.
|
|
* Windows: double click, and confirm in the UAC dialog box.
|
|
* To uninstall, run the same program but with the `-u` option.
|
|
* Linux: if coedit has been setup with `sudo` you must also uninstall with elevated privileges: `sudo ./coedit.<version>.<platform>.setup -u`.
|
|
* Windows: start a console as administrator and execute: `coedit.<version>.win32.setup -u`.
|
|
* Troubleshooting: run the setup program with the `-l` (or `--list`) option to get the status of the files and use the report to uninstall manually the files or open a ticket [here][lnk_bugtracker].
|
|
|
|
Note for the future versions:
|
|
* Updating doesn't require to uninstall.
|
|
* it's possible to uninstall from a newer setup program.
|
|
* always use the same privileges to uninstall or update as used previously.
|
|
|
|
## Binaries
|
|
|
|
* Go to [the release page](https://github.com/BBasile/Coedit/releases),
|
|
* Choose the binaries for your platform (at the bottom of an entry, the buttons labeled `coedit.<version>.<platform>.zip`).
|
|
* Extract the executables.
|
|
* Linux: it's recommended to put them in `/home/<your account>/bin`, since it's a known system PATH and that it doesn't require the super user privileges.
|
|
* Windows: the target folder must be added to your system PATH variable. When the location is not known the background tools won't work (symbol list, todo list, DCD).
|
|
|
|
Under Windows, the releases are compressed with the latest [7-zip beta](http://www.7-zip.org/) with the options _deflate-ultra_. In case of problem try to use 7zip.
|
|
Under Linux, the command line tool *zip* is used (_deflate_ and _-9_).
|
|
|
|
Under Linux you could have to set the files permission to allow their execution. This used to be necessary when
|
|
the early alpha zip were all done on Windows (files attributes were lost) but it shouldn't be the case anymore.
|
|
|
|
If they are not correctly set, for each of the following file **coedit**, **dcd-client**, **dcd-server**, **cetodo** and **cesyms**,
|
|
either set the permission in the context menu (check _allow execution_ or _executable_ depending on the desktop)
|
|
or `chmod a+x` the file in a console.
|
|
|
|
## Build the sources
|
|
|
|
_warning, these instructions are not valid for the development version. Instead [follow these](https://github.com/BBasile/Coedit/wiki/Building-the-development-version)_
|
|
|
|
Download and setup the tools:
|
|
|
|
* [Download](http://lazarus.freepascal.org/index.php?page=downloads) and setup the latest Lazarus version (1.6) and FPC + FPC sources (3.0.0) for your platform.
|
|
* Windows: the three packages are bundled in an installer. Even on Windows 64 bit, the 32 version must be setup.
|
|
* Linux: the three packages must be downloaded and setup individually. It's recommended to download the packages from _SourceForge_ and not from the official repository of the distribution because they don't always propose the latest version.
|
|
* `cd <user dir where to clone>`
|
|
* `git clone https://github.com/BBasile/Coedit.git`
|
|
* `git submodule update --init --recursive`, to clone _libdparse_, which is used by the background tools.
|
|
|
|
You're now ready to build Coedit. This can be done in the IDE or using the _lazbuild_ utility.
|
|
|
|
* _using the IDE_:
|
|
* start Lazarus,
|
|
* in the **project** menu, click *open...* and select the file **Coedit.lpi**, which is located in the sub-folder **lazproj**.
|
|
* in the menu **Execute** click **Create**.
|
|
|
|
* _using Lazbuild_:
|
|
* open a console.
|
|
* `cd` to the repository location, sub folder **lazproj**.
|
|
* type `lazbuild -B coedit.lpi` and <kbd>ENTER</kbd>. note that the path to _lazbuild_ may have to be specified.
|
|
|
|
After what Coedit should be build. The executable is output to the _bin_ folder.
|
|
|
|
|
|
|
|
Note that additionally you'll have to build [the completion daemon **DCD**][lnk_dcd], [the symbol list builder **cesyms**][lnk_cesyms] and [the todo comment parser **cetodo**][lnk_cetodo].
|
|
See the products documentation for more information.
|
|
|
|
## Linux package
|
|
|
|
Only the _x86-64_ _rpm_ is available (Fedora, openSuse, ...). After the installation, you must also build [DCD][lnk_dcd].
|
|
|
|
# How to contribute
|
|
|
|
## Development
|
|
|
|
Any Pascal or Delphi programmer who is also interested by the D language can contribute.
|
|
The process is based on _git_ and _Github_, using what's called the _fork push pull_ model:
|
|
|
|
- fork the _Coedit_ repository in your _Github_ account.
|
|
- clone this fork to your computer.
|
|
- using Lazarus and FPC, develop, fix, optimize, do whatever could improve Coedit.
|
|
- _push_ your changes to your online fork.
|
|
- propose a _pull_ request to the main Coedit repository: in [this page](https://github.com/BBasile/Coedit/compare),
|
|
- click on the link **compare across forks** and select your modified fork as *HEAD* and Coedit/master as *base* repository and validate with **Create pull request**.
|
|
|
|
[This tutorial](http://codingdiscovery.blogspot.fr/2015/01/how-to-contribute-to-github-project.html) exactly describes the procedure.
|
|
|
|
The maintainer will be notified of the request, which could be merged after review.
|
|
|
|
## Distribution
|
|
|
|
In addition to the setup program, **.deb** and **.rpm** would be welcome. They can be build using the binaries that are proposed in a zip for each release.
|
|
|
|
## Documentation
|
|
|
|
The documentation (the sources of this wiki) need to be reviewed, as it's currently written by a non native English speaker.
|
|
The wiki can be edited locally by cloning [this git repository](https://github.com/BBasile/Coedit.wiki.git).
|
|
It's also possible to propose pull requests in the main repository since the [wiki source is present](https://github.com/BBasile/Coedit/tree/master/wiki).
|
|
As tool, one of the markdown editor available on the web can be used, for example [StackEdit](https://stackedit.io/editor).
|
|
|
|
There is also a huge need to split the wiki in pages.
|
|
Because the page becomes huge and a long to load, the browsers can fail to scroll to a particular anchor.
|
|
|
|
## Bug reports
|
|
|
|
Bugs can be reported using [this dedicated online utility][lnk_bugtracker].
|
|
This place can also be used to suggest enhancements and new features.
|
|
|
|
For discussions, the official D forums [propose a section dedicated to the IDEs](http://forum.dlang.org/group/ide).
|
|
|
|
# Menu reference
|
|
|
|
## File
|
|
|
|
- **"New empty file"**: adds a new, untyped file to the source editor.
|
|
- **"New runnable module"**: adds a new file with a main() procedure. See [runnable modules][lnk_runa].
|
|
- **"Open file..."**: open a D source file from a dialog. If the file is already opened then the matching editor gets the focus.
|
|
- **"Open recent"**: displays the list of the Most Recently Used (MRU) files.
|
|
- **"Close file"**: closes the current editor with an optional warning if its content is modified.
|
|
- **"Save file"**: saves the current editor to the disk.
|
|
- **"Save all"**: saves all the files currently opened in the source editor.
|
|
- **"Save file as..."**: save the current editor using a dialog.
|
|
- **"Export html..."**: export the current editor to a html file with html-based highlighting.
|
|
- **"Add file to project"**: adds the file matching to the current editor to the project. If the current editor has been created using **"New empty file"** or **"New runnable module"** then the operation fails.
|
|
- **"Compile file"**: compile the current file. See [runnable modules][lnk_runa].
|
|
- **"Compile file and run"**: compiles the current file and execute. See [runnable modules][lnk_runa].
|
|
- **"Compile file and run outside"**: compiles the current file and execute without redirection. See [runnable modules][lnk_runa].
|
|
- **"Compile file and run..."**: compiles the current file and execute with a set of options defined in a simple input-query dialog. The arguments must be separated with spaces and can include double quotes.
|
|
- **"Run compiled file"**: tries the execute the binary produced by a previous call to _Compile file_.
|
|
- **"Run file unittests"**: compiles and runs the current file with the options **-main -unittest**. If the application option _coverModuleTests_ is set then CE will also pass **-cov** to DMD and report in the messages the lines of code that are not covered by the unit tests. This action is not usable if the current module already contains a `main()` function.
|
|
- **"Set runnable switches"**: allows to modify the switches passed to DMD when compiling a runnable module. One switch by line, invalid or duplicated switches are removed, such as _-main_ and _-unittest_ since they are set with _Run file unittests_.
|
|
- **"Verify with Dscanner"**: verifies the current file with [Dscanner](https://github.com/Hackerpilot/Dscanner). Results are displayed in the [message widget][lnk_widg_msg].
|
|
- **"View in mini explorer"**: expands the [mini-explorer][lnk_widg_miniexpl] tree on the folder that contains the current file.
|
|
|
|
## Project
|
|
|
|
- **"New project"**: closes and creates a new project (either with the native format or a DUB project). Optionally a warning is displayed if the current project is not saved.
|
|
- **"Open project"**: opens a project from a dialog.
|
|
- **"Open recent"**: displays the list of the most recently used projects.
|
|
- **"Close project"**: closes the current project. Optionally a warning is displayed if the current project is not saved.
|
|
- **"Save project"**: saves the current project.
|
|
- **"Save project as"**: saves the current project from a dialog.
|
|
- **"Project configuration"**: displays the project configuration widget.
|
|
- **"Edit project file"**: opens the project file in a new editor. When saved from a source editor, a project file is directly reloaded. It means that a particular care must be taken during the edition. Coedit will skip any error in the project file, without warnings.
|
|
- **"View project command line"**: displays the list of the switches and their arguments, as passed to DMD before the compilation. Note that under Windows, the content can be copied using the <kbd>Ctrl</kbd> + <kbd>C</kbd> shortcut on the dialog.
|
|
- **"View in mini explorer"**: expands the [mini-explorer][lnk_widg_miniexpl] tree on the folder containing the project file.
|
|
- **"Compile project"**: compiles the project using the current configuration.
|
|
- **"Compile and run project"**: compiles the project using the current configuration and execute the output if the option _binaryKind_ is set to _executable_.
|
|
- **"Compile and run project..."**: Ditto. Before the execution of the output file an input-query dialog lets you pass options to the process. Note that this command was added before the _runOptions_ of the project configuration, which allows to specify the parameters in a more advantageous way.
|
|
- **"Run project"**: tries to execute the output if the project output option _binaryKind_ is set to _executable_.
|
|
- **"Run project..."**: Ditto. Before the execution of the output file, an input-query dialog lets you specify switches and arguments to the process.
|
|
|
|
# Native projects
|
|
|
|
Coedit features a native project format completely based on the _DMD_ options.
|
|
Almost each DMD switch is represented by a project option.
|
|
|
|
The project has common parameters,
|
|
- The source files. Either modules, interfaces, static libraries or objects.
|
|
- Library aliases: a list of aliases to specify the [_libman_ entries][lnk_widg_lib] used by the project.
|
|
|
|
but most of them are specific to each configuration.
|
|
|
|
Two widgets are related to the native projects:
|
|
- [the project inspector][lnk_widg_prjinsp], allows to manage and maintain the source files list and to open them in an editor.
|
|
- [the project configuration widget][lnk_widg_prjconf], allows to manage accurately the configurations, their options
|
|
and how to execute the project output when launched from _Coedit_. For more information about the project format,
|
|
see the [project configuration][lnk_widg_prjconf] and the [project inspector][lnk_widg_prjinsp] descriptions.
|
|
|
|
The file names and directory paths can be relative.
|
|
The base directory of a relative path is always the folder where is saved the project.
|
|
They can often contain [symbolic strings][lnk_sym] and a path can be itself relative to a symbol.
|
|
The project format is cross-platform, path separators are internally converted.
|
|
|
|
Here are some more or less complex examples which illustrates the project format:
|
|
- the [metad][lnk_metad] meta repository.
|
|
- the tools written for Coedit: [cesyms][lnk_cesyms] and [cetodo][lnk_cetodo].
|
|
- [iz](https://github.com/BBasile/iz) and [dbeaengine](https://github.com/BBasile/dbeaengine)
|
|
|
|
Even if it's based on the _DMD_ options, it's also possible to compile a CE project using [LDC](https://github.com/ldc-developers/ldc) or
|
|
[GDMD](https://github.com/D-Programming-GDC/GDMD/tree/dport).
|
|
To do so, the application option _Native project compiler_ must be set accordingly.
|
|
|
|
# DUB projects.
|
|
|
|
Since the version 2, Coedit also handles [DUB](http://code.dlang.org/getting_started) projects.
|
|
|
|
DUB project description must be in [JSON format](http://code.dlang.org/package-format?lang=json), [SDL](http://code.dlang.org/package-format?lang=sdl) in not supported.
|
|
|
|
DUB projects are handled exactly as CE projects are. The _project_ menu proposes the same features
|
|
however the configuration is done in another widget, see the [dedicated paragraph][lnk_widg_dub].
|
|
|
|
# D Completion Daemon integration
|
|
|
|
The **D Completion Daemon** (DCD) is used for the completion, the function call tips, to find the declaration of a symbol and to display the _DDOC_ comment associated to a symbol.
|
|
|
|
### Setup
|
|
|
|
_DCD_ is a third part software, it's bundled in the archives distributed for each new [release](https://github.com/BBasile/Coedit/releases).
|
|
However, _DCD_ may have to be build manually, for example if a new version is released while _Coedit_ development is paused for a while.
|
|
Visit the product [homepage](https://github.com/Hackerpilot/DCD) for more information.
|
|
Note that since version 2 update 5, Coedit uses an experimental features that's not merged in the official repository.
|
|
If you wish to test it you must build [this clone](https://github.com/BBasile/DCD/tree/reboot-localusage), after checking out the right feature branch.
|
|
|
|
Once DCD build or extracted from the release archive, copy the two programs (_dcd-client_ and _dcd-server_) to the folder where the Coedit executable stands.
|
|
They can be put elsewhere, as long as the target directory is a known operating system PATH.
|
|
|
|
### Imports
|
|
|
|
In _Coedit_, _DCD_ relies on the [library manager][lnk_widg_lib] entries and on the project parameters.
|
|
If the [_libman_][lnk_widg_lib] is empty then the scope of DCD is limited to the current module or the to the current project sources and imports.
|
|
To avoid that, it's absolutely necessary to add at least _phobos_ and _core_ to the [_libman_][lnk_widg_lib] (if not automatically done the first time CE is executed).
|
|
|
|
_DCD_ also has its own configuration system. Refer to the official [_Readme_](https://github.com/Hackerpilot/DCD#configuration-files).
|
|
|
|
### Usage
|
|
|
|
- <kbd>CTRL</kbd> + <kbd>SPACE</kbd>: Calls the completion menu or auto-completes if possible. The default shortcut can be modified in the [shortcut editor][lnk_widg_opts].
|
|
- <kbd>.</kbd> invokes the completion if the editor option _autoDotDelay_ is greater than 0.
|
|
- <kbd>CTRL</kbd> + <kbd>SHIFT</kbd> + <kbd>UP</kbd>: Jumps to the declaration of the symbol located at the cursor. The default shortcut can be modified.
|
|
- <kbd>CTRL</kbd> + <kbd>LEFT MOUSE BUTTON</kbd>: ditto.
|
|
- <kbd>(</kbd>: Gets the function call tips. When functions calls are nested, call tips are stacked and separated by a group of hyphen.
|
|
- <kbd>)</kbd>: If the call tips are displayed then decreases by one the stack of call tips.
|
|
- <kbd>ESC</kbd>: Closes the call tips window, whatever is the level of the stack.
|
|
- <kbd>CTRL</kbd> + <kbd>F2</kbd>: Renames the identifier for the symbol located at the cursor position. This works only if the symbol is declared in this module.
|
|
|
|
Documentation comments associated to a symbol are displayed when the cursor motion stops over a symbol.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
When Coedit starts and if the DCD server is not already listening then it's launched by CE.
|
|
When Coedit stops, the server is only terminated if it was not already running when starting.
|
|
|
|
If the DCD server crashes while Coedit is running then both must be restarted.
|
|
|
|
It's also advisable to setup [Dscanner](https://github.com/Hackerpilot/Dscanner), from the same author, as a Coedit [custom tool][lnk_widg_tools].
|
|
|
|
# Docking
|
|
|
|
Coedit interface is divided into a small dozen of dockable widgets. Except the code editor, each widget
|
|
can be dragged in another widget or to one of its edges. To avoid any error, the layout can be locked when right clicking a header:
|
|
|
|
|
|
|
|
Layouts can be saved or reloaded from the main menu:
|
|
|
|
|
|
|
|
Docking can be customized in the [option editor][lnk_widg_opts]:
|
|
|
|
|
|
|
|
Note that the docking relies on a component that's in beta state and problems might be encountered:
|
|
- many small windows appear when CE is launched: the widgets are actually all independent forms that are created before being docked, under a Windows system they are visible for a second.
|
|
- space between the menu and the workspace: the splitter can be moved when pressing the <kbd>CTRL</kbd> key.
|
|
- strange looking layout after reloading (missing splitter between two widgets, or nothing between two splitters): close CE, delete the configuration file named _docking.xml_ from the [data folder][lnk_widg_opts], after what Coedit will start with the default layout.
|
|
- other problem: [file an issue][lnk_bugtracker].
|
|
|
|
# Widgets
|
|
|
|
## Editor widget
|
|
|
|
The _source editor widget_ is a standard code editor, specialized for highlighting D source files.
|
|
|
|
|
|
|
|
#### Overview
|
|
|
|
- folding: curly brackets blocks, multi-line strings, block comments, nested block comments, DDoc comments blocks.
|
|
- colorization of the following categories: attributes, keywords, special keywords, numbers, symbols, comments, assembler, DDoc comments.
|
|
- current identifier markup, selection markup.
|
|
- standard keyboard navigation shortcuts <kbd>CTRL</kbd> + [<kbd>SHIFT</kbd> +] <kbd>LEFT</kbd> | <kbd>RIGHT</kbd>, <kbd>CTRL</kbd> + <kbd>HOME</kbd>, <kbd>CTRL</kbd> + <kbd>END</kbd> etc.
|
|
- macro recording and playback using <kbd>CTRL</kbd> + <kbd>SHIFT</kbd> + <kbd>R</kbd> (start or stop recording) or <kbd>CTRL</kbd> + <kbd>SHIFT</kbd> + <kbd>P</kbd> (play).
|
|
- synchro-edit (activated when clicking the pen icon located in the gutter, or with the shortcut <kbd>CTRL</kbd> + <kbd>E</kbd> and <kbd>CTRL</kbd> + <kbd>SHIFT</kbd> + <kbd>E</kbd>).
|
|
- zoom: <kbd>CTRL</kbd> + <kbd>WHEEL</kbd>, <kbd>CTRL</kbd> + <kbd>MIDDLE MB</kbd>, <kbd>CTRL</kbd> + <kbd>+</kbd> | <kbd>-</kbd> | <kbd>.</kbd>.
|
|
- display cache: for each document, the zoom ratio, the folding state and the caret position are saved between two sessions. A cache file has a fixed life-time of three months from its last modification.
|
|
- drag & drop editing.
|
|
- external modification tracking. Each time the focus is put on a document (switch document, show & hide application), Coedit verifies if its time stamp has changed.
|
|
- static macros.
|
|
- custom folded regions.
|
|
- huge amount of options.
|
|
- split view: two editors in one page.
|
|
- most recent location buffer: instead of bookmarks, the most recent caret positions are stored in a buffer. Positions can be recovered with the lateral mouse buttons (_X1_ & _X2_) or with the multimedia keyboard keys _next web page_ & _previous web page_.
|
|
|
|
#### Custom regions
|
|
|
|
The custom regions are defined in single line comments.
|
|
A region starts with a comment that ends with at least three hyphens and a plus symbol.
|
|
A region stops with a comment ending with at least four hyphens.
|
|
|
|
Two valid examples:
|
|
|
|
```D
|
|
// ctor/dtor -------------+
|
|
this(string s){}
|
|
this(uint u){}
|
|
~this(){}
|
|
// ------------------------
|
|
|
|
// operators overloads ---+
|
|
void opIndexAssign(size_t i; T t){}
|
|
T opIndex(size_t i){}
|
|
// ----
|
|
```
|
|
|
|
Regions are saved and reloaded with the editor cache. They give a clear and compact view of a module:
|
|
|
|
|
|
|
|
#### Static macros
|
|
|
|
The static macros can be described as *parameter-less code snippets*.
|
|
A static macro starts with the dollar symbol and ends with an alphabetic character.
|
|
For example after typing `$a`, `auto` is inserted.
|
|
Confer with the [source code](https://github.com/BBasile/Coedit/blob/master/src/ce_staticmacro.pas#L57) too see the pre-defined macros list.
|
|
Custom macros can be edited in the [options editor][lnk_widg_opts]:
|
|
|
|
|
|
|
|
#### Editor options
|
|
|
|
Editor options are displayed in the [option editor][lnk_widg_opts].
|
|
They cover many aspects of the editor:
|
|
- highlighterDlang: options for D2 highlighter such as colors, font styles, folding, etc.
|
|
- highlighterText: options for generic highlighter such as colors, font styles, etc.
|
|
- ddocDelay, autoDotDelay: tweak how fast [DCD][lnk_dcd] features are.
|
|
- options1 & options2: about 50 boolean options to define if the special characters are shown, if the trailing spaces are trimmed, if the tabs are converted to spaces, etc.
|
|
- and much more.
|
|
|
|
|
|
|
|
The shortcuts are editable from the [option editor][lnk_widg_opts], category _Shortcuts, Code editor_:
|
|
|
|
|
|
|
|
#### Split view
|
|
|
|
The split view allows to pin one of the document to the right of the other documents.
|
|
To pin a document, open it in an editor and click the right-most toolbar button.
|
|
The other editors will get this document displayed at their right.
|
|
To unpin a document, select its initial page and click the same button.
|
|
The document to pin can be replaced on the fly, still using the same button, and even if the split view is already active.
|
|
|
|
|
|
|
|
It's useful to display a module that contains the declarations of a library binding since it's not anymore necessary to change the editor page to verify the members of an enum or the parameters of a function.
|
|
Note that the action _jump to declaration_ (see [DCD][lnk_dcd]) is adapted so that the page index is not modified if the declaration definition is in the document that's pined to the right.
|
|
|
|
#### Helpers
|
|
|
|
The editor proposes two useful actions to (un)comment blocks of code.
|
|
The action _invert version all none_ changes the `version(none)` statements to `version(all)` statements and vice versa. When no selection is available this is applied to the whole document.
|
|
The action _comment selection_ adds or removes the `\\` located at the beginning of each line in the current selection.
|
|
|
|
Another important helper is the brace auto-closing. By default it's not activated. Several modes are proposed:
|
|
- _autoCloseNever_: deactivate the feature.
|
|
- _autoCloseAtEof_: closes a brace after a `{` located at the end of file.
|
|
- _autoCloseAlways_: closes a brace after a `{`.
|
|
- _autoCloseLexically_: closes a brace after a `{` if the count of braces pairs is odd.
|
|
- _autoCloseOnNewLineEof_: closes a brace after a `{` located at the end of file but only after <kbd>ENTER</kbd>.
|
|
- _autoCloseOnNewLineAlways_: closes a brace after a `{` but only after <kbd>ENTER</kbd>.
|
|
- _autoCloseOnNewLineLexically_: closes a brace on <kbd>ENTER</kbd> and if the count of braces pairs is odd.
|
|
|
|
## Find & replace widget
|
|
|
|
The _find and replace_ widget allows to find and replace text patterns in the focused source editor.
|
|
|
|
|
|
|
|
- first field: the pattern to find.
|
|
- second field: the pattern used as replacement, only active when **"replace with"** is checked.
|
|
- whole word: only search for the whole pattern.
|
|
- backward: search from the current position to the top.
|
|
- from cursor: when unchecked, the operation always starts from the top of the document.
|
|
- case sensitive: when unchecked, the case is ignored.
|
|
- prompt: a confirmation is required to replace a match.
|
|
- allow regex: when checked, the search is performed by a regex engine (which doesn't mean that the pattern to find has to be a regex).
|
|
|
|
By default <kbd>CTRL</kbd> + <kbd>F</kbd> is used to pass the current identifier to the first field and <kbd>F3</kbd> to execute a search.
|
|
_Find all_ results are displayed in the [messages widget][lnk_widg_msg], with a context and they are clickable.
|
|
|
|
|
|
|
|
The scope of _Find all_ can be set, either to the current editor or to the whole project, by clicking the icon at the right.
|
|
|
|
Notes:
|
|
- To find the declaration of a symbol, <kbd>Ctrl</kbd> + <kbd>MB Left</kbd> or the [symbol list][lnk_widg_symlist] are faster.
|
|
- To rename a variable or a type, local identifier renaming (<kbd>Ctrl</kbd> + <kbd>F2</kbd>) can be more accurate than _Replace all_ since this uses the semantic.
|
|
|
|
## Library manager widget
|
|
|
|
The library manager (aka the _libman_) is designed to replace the _sc.ini_ or the _sc.conf_ file to manage the static libraries.
|
|
Despite of its simplistic look it's a central component of the software.
|
|
|
|
The _libman_ links the library files (_*.lib_ or _*.a_) to their D sources and are represented with a simple **alias** that is used in different part of the software.
|
|
For example, in a project, you don't need anymore to specify the **-I** path nor its matching library file name.
|
|
Coedit handles the task automatically (see later in the project configuration widget, [general options][lnk_widg_prjconf_gen]).
|
|
|
|
|
|
|
|
- : add a library item, by default its fields are initialized with _n/a_.
|
|
- : remove the selected item.
|
|
-  **/** : change selected entry position.
|
|
- : if the current project _binaryKind_ is set to _staticlib_ then the _libman_ will use its parameters to create an entry. This avoids to browse in the dialogs, for example if you wish to setup several [_metad_][lnk_metad] items. Note that sometimes the sources root folder has to be adjusted.
|
|
- : if the selected item defines a _project_ then closes current project and opens the one matching to the entry.
|
|
- : allows to fetch the master version of a [DUB registry item](http://code.dlang.org/). When the button is clicked, a dialog is displayed. It allows to type the name of the library to download or to select a library in a list obtained from the official repository. After validation and if the name is valid, the library will be downloaded, compiled and a new entry automatically filled. This features is actually more useful for the CE projects and the runnable modules since the dependencies of a DUB projects are handled automatically. It allows to use any DUB library in a CE project, even if the package doesn't include a CE project file. Note well that this feature works even if the target project is described with the _SDL_ format.
|
|
- : enable or disable the selected entry. This is mainly useful to test new DMD versions since the libraries often have to be recompiled from a version to another.
|
|
- : edit the item alias.
|
|
- : select the library file. In some rare case, this field can be omitted (for example if the library file is set in the _sc.ini_).
|
|
This can be skipped if the library is only a small orphan _d_ source that's not been compiled as a static library or if the entry is only used for the [DCD][lnk_dcd] completion.
|
|
- : select a folder that contains several libraries files or several orphans modules.
|
|
- : select the sources root folder. (the one commonly named 'import').
|
|
- : set the project file that matches to the selected item.
|
|
|
|
If they're not automatically detected, it's recommended to add the _runtime library_ and _phobos_.
|
|
A collection of third party libraries are provided by the [_metad_][lnk_metad] repository.
|
|
All of them can be easily build in Coedit and setup in the [_libman_](lnk_widg_lib).
|
|
|
|
The library entries are saved in the user folder [(see options)][lnk_widg_opts] as _libraryManager.txt_.
|
|
|
|
## Project inspector widget
|
|
|
|
The project inspector widget is mostly designed to manipulate the project source files. It can also be used to select a compiler configuration.
|
|
|
|
|
|
|
|
- : adds a D source to the project from a dialog. The new source is not directly opened in the editor. To add a file that is already edited, rather use **"Add file to project"** from the **File** menu.
|
|
- : removes the selected source (_selected_ in the widget tree, not in the editor) from the project.
|
|
- : adds a folder of D source to the project from a dialog. The procedure is recursive.
|
|
|
|
Note that instead of using the dialogs to add files, it's also possible to drop items from a file explorer.
|
|
|
|
## Project configuration widget
|
|
|
|
The project configuration widget is a powerful editor for the compiler options. By design it uses an "_Object Inspector_" GUI element.
|
|
If this choice has avoided a painful GUI designing work, it also perfectly represents the way the classes that encapsulates the compiler options have been programmed. (see _ce_dmdwrap.pas_).
|
|
|
|
The following paragraphs specify exactly which _DMD_ switch is generated for an option,
|
|
however these values are not anymore exact when CE is tweaked to compile its project format with _LDC2_ since
|
|
the _DMD_ switches are translated for _LDC2_ through the compatibility tool _LDMD2_.
|
|
|
|
- : adds a new compiler configuration. An input-query dialog allows to directly set its name (see the above note about the configuration name).
|
|
- : removes the current compiler configuration.
|
|
- : clones the current compiler configuration.
|
|
-  **/** : de/activates the synchro-mode. When activated, each particular option edited will be copied to the other configurations.
|
|
|
|
Notes:
|
|
- changing the configuration name is only possible in the section [**All Categories**](https://github.com/BBasile/Coedit/wiki#all-categories), field **name**.
|
|
|
|
#### General options:
|
|
|
|
The general options are common to each configuration.
|
|
|
|
|
|
|
|
- Configuration index: selects a configuration by its index. This property exists only for the project persistence.
|
|
To select a configuration, rather uses the project inspector or the combo-box at the top of the widget.
|
|
- libraryAliases: shows a small editor used to specify the aliases of the libraries used by the project.
|
|
One item per line. An item text must match to an entry of the [_libman_][lnk_widg_lib]. It avoids the addition of the **-I** options and the additional sources.
|
|
When dependencies are complex, it's possible to select all the entries by setting the first line of the editor to a single asterisk `*`.
|
|
Thanks to this shortcut you don't have to remember if an aliased library is using another library but be warned that compilation speed can be impacted.
|
|
Note that unless the project _binaryKind_ is set to _executable_ or _sharedlib_ the static libraries selected from this list are not linked.
|
|
- RootFolder: the project file is not necessarily indicating the root of the project folder.
|
|
This field can be used to specify another one, either relative or absolute. This is useful to run a custom tool using the *CPR* [symbolic string][lnk_sym] (e.g: git, recursive cleaning).
|
|
- Sources: shows a dialog used to edit the filenames of the project sources. Relative paths are automatically handled. Only one item must stand by line.
|
|
It's recommended to use the [project inspector][lnk_widg_prjinsp] instead of this archaic editor. To include a folder of source it's also possible to specify a path with a asterisk in the **Paths** options, **extraSources** editor.
|
|
This avoids to manually remove the obsolete source or to manually add the new source files.
|
|
|
|
#### Message options:
|
|
|
|
Groups the options related to the messages emitted by the compiler.
|
|
These options are defined per-configuration.
|
|
|
|
|
|
|
|
- deprecationHandling: sets the way deprecations must be handled (among _silent_ or _error_, **-ds** or **-de**, the default value, _warning_, does not produce a switch)
|
|
- quiet: sets if non essential compiler messages are skipped. (**-quiet**)
|
|
- showColumnsNumber: sets if the horizontal position is shown in the messages. (**-vcolumns**)
|
|
- showHiddenAlloc: if sets then display potentially hidden GC allocations. (**-vgc**)
|
|
- tlsInformations: sets if thread local storage information are displayed. (**-vtls**)
|
|
- verbose: sets if verbose. (**-v**)
|
|
- warnings: sets if the warnings are displayed. (**-w**)
|
|
- warningsAsInfo: defines if the warnings don't prevent the project to be compiled.
|
|
|
|
#### Debugging options:
|
|
|
|
Groups the options related to the debugging information added to the output binary.
|
|
These options are defined per-configuration.
|
|
|
|
|
|
|
|
- codeviewCformat: generate debug info using the _codeview_ format. (**-gc**)
|
|
- codeviewDexts: adds D _codeview_ extensions. (**-g**)
|
|
- debug: sets if debug information are generated. (**-debug**)
|
|
- debugLevel: sets the debugging level. (**-debug=x**)
|
|
- debugIdentifiers: list of debug identifiers. (for each item **-debug=item** is generated). One item per line.
|
|
- generateMapFile: sets if a map file is generated. (**-map**)
|
|
|
|
#### Documentation options:
|
|
|
|
Groups the options related to the generation of the project documentation.
|
|
These options are defined per-configuration.
|
|
|
|
|
|
|
|
- documentationDirectory: sets the directory where the documentation is generated. It can be a relative path. (**-Dd**)
|
|
- generateDocumentation: sets if the documentation is generated. This field is constrained to _true_ if the doc path is defined. (**-D**)
|
|
- generateJSON: sets if the JSON documentation is generated. This field is constrained to _true_ if the JSON file name is defined. (**-X**)
|
|
- JSONFilename: sets the JSON file name. (**-Xf**)
|
|
|
|
#### Output options:
|
|
|
|
Groups the options related to the code generation.
|
|
These options are defined per-configuration.
|
|
|
|
|
|
|
|
- addMain: adds an empty _main()_ procedure. (**-main**)
|
|
- alwaysLinkStaticLibs: under Windows this option forces to link a static library selected in the _LibraryAliases_ even if not required (for example if the project is itself a static library).
|
|
- binaryKind: sets the compiler output kind among: **"staticlib"**, **"sharedlib"**, **"executable"** and **"object"**. (it matches respectively to **-lib**, **-shared**, nothing, **-c**).
|
|
- boundsCheck: sets the bounds checking mode, among **"alwaysON"**, **"alwaysOFF"** and **"safeOnly"**. (**-boundscheck=on** or **-boundscheck=off** or **-boundscheck=safeonly**). The switch is not generated when it's a default value.
|
|
- generateStackFrame: forces the generation of stack frames. (**-gs**)
|
|
- inlining: try to inline functions and procedures. (**-inline**)
|
|
- Optimizations: optimize. (**-O**)
|
|
- release: do not generate the assertions and the contracts. (**-release**)
|
|
- targetKind: sets the target registry size, among **auto**(same as current OS) **os32** (targets a 32 bit OS) and **os64** (targets a 64 bit OS). It should usually remain to **auto** however this can be used to verify the portability of the project. (**-m32**, **-m64**)
|
|
- unittest: generates the unittest code. (**-unittest**)
|
|
- versionIdentifiers: list of version identifiers. One per line, the switches **-version=** are added automatically. An entry can be disabled by prefixing it with a semicolon or a pair of backslash.
|
|
|
|
#### Other Options:
|
|
|
|
|
|
|
|
Most of the existing switches are hard-coded however for the few missing ones this field can be used (e.g: the linker flags). In the dialog respect the following rules:
|
|
- the switches must be included. (e.g: an additional version identifier must include the whole prefix _-version=_)
|
|
- an entry must not be double quoted, even if it contains a file name with spaces. (they are automatically added later)
|
|
- one item per line.
|
|
- no leading or trailing spaces.
|
|
- an entry can be disabled if it's prefixed by a semicolon or a by pair of backslash.
|
|
|
|
These custom switches are defined per-configuration.
|
|
|
|
#### Path options:
|
|
|
|
Groups the options defining the location of the files used or produced by the compiler.
|
|
These options are defined per-configuration.
|
|
|
|
|
|
|
|
- exclusions: paths or files to exclude from the main sources. The items can contain [symbolic strings [lnk_sym]. The items can be global [match expressions](https://en.wikipedia.org/wiki/Glob_(programming)).
|
|
- extraSources: either _*.lib_, _*.a_, _*.o_ and _*.obj_, files or _*.d_, _*.di_ source files. If a path that ends with an asterisk is added (e.g: _folderA\folderB\*_) then every source files located in this folder and its sub-folders will be passed to the compiler.
|
|
- forceExtension: when set, the output filename has always the right file extension. This option is useful when the _outputFilename_ contains periods but no extension (example: `-offoo.bar` under linux generates the executable `foo.bar` but under windows and if the option is set `foo.bar.exe`).
|
|
- importModulePaths: a list of paths where _DMD_ has to look for the libraries sources. (**-I**)
|
|
- importStringPaths: a list of paths used to solve the `import(file)` expressions. (**-J**)
|
|
- objectDirectory: the directory where object files (_*.o_ or _*.obj_) must be written. (**-od**)
|
|
- outputFilename: the output filename. The identifier should only include a period to specify a non default extension otherwise it prevents _DMD_ to add the default one. (**-of**)
|
|
|
|
#### Pre/Post build process options:
|
|
|
|
They define the options of two processes and a bunch of commands, respectively executed before and after the compilation.
|
|
These options are defined per-configuration.
|
|
These options are not compatible with the system of _base_ & _overridden_ configuration.
|
|
|
|
|
|
|
|
- executable: the executable file name. If the system cannot solve its path using the environment variables then it must be included.
|
|
It can also be represented by a [symbolic string][lnk_sym].
|
|
- options: a set of options. Activate **poUsesPipe** and **poStdErrToOutput** if you wish to redirect the process output to the messages widget.
|
|
- parameters: a list of switches and arguments. As usual, one item per line, no double quotes.
|
|
- showWindow: sets how the program window is displayed.
|
|
- simpleCommands: additionally to the process, a list of shell commands can be specified, they are executed before the pre/post process. The commands have fixed options: always piped to the message widget, the working directory is always the project path.
|
|
The commands can contain [symbolic strings][lnk_sym].
|
|
|
|
The pre-build process is always executed, even if the project has no source files.
|
|
This can be used as a trick to compile from another tool.
|
|
|
|
An interesting post-build process feature is that it can be set on the executable that's just been build.
|
|
This is possible when the post compilation process _executable_ is set to the [symbolic string][lnk_sym] **`<CPO>`**, which is expanded to the name of the file produced by the compiler.
|
|
|
|
#### Run options:
|
|
|
|
|
|
|
|
They define the options applied when running the project output (e.g: menu **"project"**, **"compile and run"**).
|
|
The _executable_ field is not present because it relies on the project parameters (**-of** for a CE project and the combination of _targetPath_ with _targetName_ for a DUB project).
|
|
|
|
If the output is piped then the [process input widget][lnk_widg_procinp] can be used to pass the input to the program being executed.
|
|
These options are defined per-configuration.
|
|
These options are not compatible with the system of _base_ & _overridden_ configuration.
|
|
|
|
#### All categories
|
|
|
|
Unfiltered options, sub categories can be expanded or collapsed.
|
|
|
|
- name: the current configurations name.
|
|
- isBaseConfiguration: when set, the current configuration defines the default options of a configuration which is set as overridden.
|
|
- isOverriddenConfiguration: when set, the options of the current configuration are only handled if they don't match to the base configuration or if the base configuration is not set. This system avoids to edit using the synchro-mode.
|
|
|
|
|
|
|
|
## DUB project editor
|
|
|
|
The DUB project editor is widget is divided in two panels:
|
|
|
|
#### Inspector
|
|
|
|
|
|
|
|
The first panel displays the source list and the combination of _each build type_ with each _build configuration_. A source can be opened in a new editor by a double click.
|
|
Selecting a configuration defines which _buildType_ type and which _configuration_ will be build by DUB when clicking _compile_ in the _project_ menu.
|
|
Note that it's possible to specify which compiler DUB uses in the application options _dubCompiler_.
|
|
|
|
#### Editor
|
|
|
|
The second panel displays the tree of the project properties. The can be modified in the field at the bottom.
|
|
|
|
|
|
|
|
New properties can be added or removed:
|
|
|
|
* : removes the selected property. Note that the effect is not reflected until the project is saved as a file (since Coedit does not communicate directly with DUB).
|
|
* : shows a small dialog that allows to add a new value, a new array or a new object. This requires to master the [DUB JSON format](http://code.dlang.org/package-format?lang=json). In the dialog, the value of the text field is only used when an object or a value is added. It matches to the _key_, not the value itself.
|
|
|
|
|
|
|
|
## Dfmt Commander
|
|
|
|
The _Dfmt commander_ widget is a simple but complete interface for the D source code formater [Dfmt](https://github.com/Hackerpilot/dfmt). The background tool has to be build and installed in one of the _PATH_ known by the operating system.
|
|
|
|
|
|
|
|
A property inspector allows to tweak the format. See the [official documentation](https://github.com/Hackerpilot/dfmt#configuration) to learn more about the options.
|
|
|
|
- : apply the formatting. The editor state is backed up before each formatting.
|
|
- : restore the previous backup.
|
|
|
|
The formatting is applied in memory and is undo-able either from the widget or from the code editor. The changes are not physically applied until the file is explicitly saved.
|
|
Formatting options are saved between each session in the [Coedit data folder][lnk_widg_opts].
|
|
|
|
## Todo list
|
|
|
|
The _todo list_ widget displays the _todo comments_ located in the source files.
|
|
|
|
|
|
|
|
When no source file is opened but a project is, the widget displays the comments of the whole project.
|
|
When a source file has the focus but is not part of the project the widget only displays the items located in this file.
|
|
Otherwise if a file has the focus and if it's part of the project then the whole project *todos* are displayed.
|
|
|
|
By default the list is refreshed automatically but it can be advisable to disable this option
|
|
if the project contain a huge SLOC count. This can be deactivated in the context menu or in the [options editor][lnk_widg_opts]:
|
|
|
|
|
|
|
|
It's possible to jump to a particular item in its file with a double click.
|
|
The items cannot be edited in the widget.
|
|
|
|
- : refreshes the list manually .
|
|
- : jump to the item declaration.
|
|
|
|
The _todo comments_ must follow this format:
|
|
> TODO -cCategory -aAssignee -pPriority -sStatus : what
|
|
|
|
The fields (-a -c -p -s) are optional but the _what_ is mandatory.
|
|
The format is more detailed in the [tool source code](https://github.com/BBasile/Coedit/blob/master/cetodo/cetodo.d#L7).
|
|
The tool itself can be build with Coedit.
|
|
|
|
## Mini explorer widget
|
|
|
|
The mini explorer provides basic file browsing within the IDE.
|
|
|
|
|
|
|
|
- : adds the selected folder to the favorites.
|
|
- : removes the selected favorite folder.
|
|
- : lets the shell open the selected folder or execute the selected file.
|
|
- : if the selected file is a native or a DUB project then opens it as a project otherwise opens it in a new code editor.
|
|
- ***input field***: filter the files whose name contains the text typed.
|
|
|
|
The favorite folders are persistent. The file list supports drag and drop. A few options are available in the [option editor][lnk_widg_opts].
|
|
|
|
# Detailed and illustrated tutorials
|
|
|
|
## New project flow
|
|
|
|
In this tutorial will see how to start a _Coedit_ project from scratch.
|
|
|
|
- Start _Coedit_ or create a new project.
|
|
- In the **File** menu, click **New empty file**.
|
|
|
|
- Add the `main()` function.
|
|
|
|
- Save the file where you wish to, using the action **Save as**.
|
|
|
|
- Still in the **File** menu, click **Add file to project**. The file we've just saved will be added to the project sources.
|
|
|
|
- At this time, the project can be already compiled, even without being saved.
|
|
However save it somewhere. In the project inspector, the source path will be displayed relatively to the project location.
|
|
|
|
- You can now compile the project.
|
|
|
|
|
|
## Using a runnable module as an interactive command interpreter
|
|
|
|
In this tutorial, we'll see that a Coedit runnable module can
|
|
be used to program an interactive command interpreter, completely
|
|
integrated to the IDE thanks to the automatic redirection of
|
|
the input and the output streams.
|
|
|
|
Create a new runnable module.
|
|
In a first time we need a loop that waits for a command to process.
|
|
The input is split into command and arguments.
|
|
The raw input is used to test the program termination:
|
|
|
|
```D
|
|
module interactive.command.interpreter;
|
|
|
|
import std.stdio;
|
|
import std.array;
|
|
|
|
string[] arguments;
|
|
string command;
|
|
|
|
void main(string[] args)
|
|
{
|
|
string input;
|
|
while (true)
|
|
{
|
|
input = readln;
|
|
if (input == "exit\n") return;
|
|
// split command and args
|
|
auto s = split(input);
|
|
if (s.length){
|
|
command = s[0];
|
|
if (s.length > 1)
|
|
arguments = s[1..$];
|
|
else
|
|
arguments.length = 0;
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Now we add a bunch of trivial command processors. They are dispatched with the help of an associative array:
|
|
|
|
```D
|
|
module interactive.command.interpreter;
|
|
|
|
import std.stdio;
|
|
import std.array;
|
|
|
|
string[] arguments;
|
|
string command;
|
|
void function()[string] dispatcher;
|
|
|
|
static this(){
|
|
dispatcher["hello"] = &hello;
|
|
dispatcher["showargs"] = &showArgs;
|
|
}
|
|
|
|
void showArgs(){
|
|
foreach(arg;arguments) writeln(arg);
|
|
}
|
|
void hello(){
|
|
writeln("hello world");
|
|
}
|
|
|
|
void main(string[] args)
|
|
{
|
|
string input;
|
|
while (true)
|
|
{
|
|
input = readln;
|
|
if (input == "exit\n") return;
|
|
// split command and args
|
|
auto s = split(input);
|
|
if (s.length){
|
|
command = s[0];
|
|
if (s.length > 1)
|
|
arguments = s[1..$];
|
|
else
|
|
arguments.length = 0;
|
|
if (command in dispatcher)
|
|
dispatcher[command]();
|
|
else
|
|
writeln("unrecognized command: ", command);
|
|
stdout.flush;
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
You can now click, in the **run** menu **compile and run file**.
|
|
Use the [process input widget][lnk_widg_procinp] to pass a command and their optional arguments to the interpreter,
|
|
for example `hello` and press <kbd>ENTER</kbd>:
|
|
|
|
|
|
|
|
Then, if not already done, save the module written for this tutorial and type
|
|
`showargs <CFF> <CAF> <CAP>` and press <kbd>ENTER</kbd>, the [symbolic strings][lnk_sym] will be expanded by the process-input-widget before being
|
|
sent as input.
|
|
|
|
|
|
|
|
To finish type "exit" and press <kbd>ENTER</kbd>.
|