Debian Codegraph @

modules/lsp-plugins-shared/src/doc/manuals/development/eclipse.php

raw
1 <?php
2 $IMG = $RES_ROOT . "/img/devel/";
3 ?>
4 <p>LSP Plugins may be easily developed using <a href="https://www.eclipse.org/ide/">Eclipse IDE</a></p>
5
6 <h2>Configuring project and build</h2>
7
8 <p>First of all, you need to install the following plugins:</p>
9 <ul>
10 <li><b>Eclipse C/C++ Development Tools (CDT)</b> - for C/C++ development</li>
11 <li><b>Eclipse EGit</b> - for GIT integration</li>
12 </ul>
13
14 <p>First of all, you need to checkout GIT repository into your workspace by
15 issuing the following command:</p>
16 <pre>
17 cd &lt;workspace-path&gt;
18 git clone https://github.com/sadko4u/lsp-plugins.git lsp-plugins
19 cd lsp-plugins
20 git checkout -b &lt;your-branch&gt; origin/devel
21 </pre>
22
23 <p>Now we can switch to C++ development perspective by selecting
24 <b>Window</b> &rarr; <b>Perspective</b> &rarr; <b>Open Perspective</b> &rarr; <b>Other...</b></p>
25 <div class="images">
26 <img src="<?= $IMG ?>eclipse-cpp-perspective.png">
27 </div>
28
29 <p>After switching to C/C++ perspective, select <b>File</b> &rarr; <b>New</b> &rarr; <b>C/C++ Project</b></p>
30 <p>In the opened dialog, select <b>C++ Managed Build</b> template, then click <b>Next</b></p>
31 <div class="images">
32 <img src="<?= $IMG ?>eclipse-cpp-template.png">
33 </div>
34
35 <p>Enter the folder name same to the folder of the GIT repository, select <b>Executable</b> &rarr; <b>Empty Project</b>,
36 <b>Linux GCC</b>, then click <b>Finish</b></p>
37 <div class="images">
38 <img src="<?= $IMG ?>eclipse-new-project.png">
39 </div>
40
41 <p>Now, complete project structure is visible in the <b>Project explorer</b> view.</p>
42 <div class="images">
43 <img src="<?= $IMG ?>eclipse-project-explorer.png">
44 </div>
45
46 <p>We just need to configure project build. For this case, select <b>Project</b> &rarr; <b>Properties</b> menu,
47 the project configuration dialog should appear:</p>
48 <div class="images">
49 <img src="<?= $IMG ?>eclipse-project-properties.png">
50 </div>
51
52 <p>Go to <b>C/C++ Build</b> &rarr; <b>Settings</b> and, first of all, select <b>Configuration</b> combo
53 to <b>[ All Configurations ]</b>, this will apply all modified settings to all build targets.</p>
54 <p>Select <b>GCC C++ Compiler</b> &rarr; <b>Dialect</b> section and select the <b>ISO C++98</b> as a <b>Language Standard</b>:</p>
55 <div class="images">
56 <img src="<?= $IMG ?>eclipse-project-lang-std.png">
57 </div>
58
59 <p>Select <b>GCC C++ Compiler</b> &rarr; <b>Preprocessor</b> section and add following macros to <b>Defined Symbols</b>:</p>
60 <ul>
61 <li><b>LSP_TRACE</b> - this macro will enable output of trace information to the console while running code in debug environment.</li>
62 <li><b>LSP_IDE_DEBUG</b> - makes invisible set of main() functions that are defined in source code of different tools.</li>
63 <li><b>LSP_TESTING</b> - enables unit testing subsystem in build.</li>
64 </ul>
65 <p>Finally, the window should look like:</p>
66 <div class="images">
67 <img src="<?= $IMG ?>eclipse-preprocessor-setup.png">
68 </div>
69
70 <p>Now we need to define additional location of header files. Select <b>GCC C++ Compiler</b> &rarr; <b>Includes</b>
71 and add to the <b>Include paths</b> the following line:</p>
72 <pre>
73 ${workspace_loc:/${ProjName}/include}
74 </pre>
75 <p>The window should look like:</p>
76 <div class="images">
77 <img src="<?= $IMG ?>eclipse-project-includes.png">
78 </div>
79
80 <p>Now we need to enable extra headers for additional packages, for this purpose visit <b>GCC C++ Compiler</b> &rarr; <b>Miscellaneous</b>
81 and enter into the <b>Other flags</b> field the following string:</p>
82 <pre>
83 -c -fmessage-length=0 -m64 -msse -msse2 `pkg-config --cflags jack x11 cairo lv2 sndfile gl`
84 </pre>
85 <p>Also, check the <b>Position Independent Code (-fPIC)</b> flag:</p>
86 <div class="images">
87 <img src="<?= $IMG ?>eclipse-project-misc.png">
88 </div>
89
90 <p>Select <b>GCC C++ Linker</b> &rarr; <b>General</b> settings and enable the <b>Support for pthread (-pthread)</b> option:<p>
91 <div class="images">
92 <img src="<?= $IMG ?>eclipse-project-linker-general.png">
93 </div>
94
95 <p>Select <b>GCC C++ Linker</b> &rarr; <b>Libraries</b> settings and add the following libraries to the list:
96 <ul>
97 <li>pthread</li>
98 <li>dl</li>
99 </ul>
100 <div class="images">
101 <img src="<?= $IMG ?>eclipse-project-linker-libraries.png">
102 </div>
103
104 <p>Select <b>GCC C++ Linker</b> &rarr; <b>Miscellaneous</b> settings and enter the following string to <b>Linker flags</b> field
105 to enable linkage with external libraries:<p>
106 <pre>
107 `pkg-config --libs jack x11 cairo lv2 sndfile gl`
108 </pre>
109 <p>The window should look like:</p>
110 <div class="images">
111 <img src="<?= $IMG ?>eclipse-project-linker-misc.png">
112 </div>
113
114 <p>To make resources generated by makefile invisible to IDE, we need to add <b>.build</b> path as excluded from source tree.
115 For this purpose, visit <b>Resource</b> &rarr; <b>Resource Filters</b>, click <b>Add Filter</b></p>
116 <p>Set <b>Filter type</b> to <b>Exclude all</b>, <b>Applies to</b> - <b>Folders</b>, <b>All children (recursive)</b>,
117 <b>Name</b> <b>Matches</b> <b>.build</b>. The result should look like:</p>
118 <div class="images">
119 <img src="<?= $IMG ?>eclipse-project-exlude-resource.png">
120 </div>
121
122 <p>To optimize build, we can enable more than one thread for build. For this purpose, select
123 <b>C/C++ Build</b> &rarr; <b>Behavior</b> and click <b>Enable Parallel Build</b>, <b>Use optimal jobs</b>:</p>
124 <div class="images">
125 <img src="<?= $IMG ?>eclipse-project-build.png">
126 </div>
127
128 <p>Now we can click <b>Apply and Close</b> button and launch build by issuing <b>Project</b> &rarr; <b>Build</b> menu item.</p>
129
130 <h2>Debugging Project</h2>
131
132 <p>To start debugging, simply issue <b>Run</b> &rarr; <b>Debug as</b> &rarr; <b>Local C/C++ Application</b>, Eclipse IDE will
133 automatically create configuration for launching build that can be reused in future.</p>
134 <p>The main() function launches testing subsystem, so in console output we will get the following string:</p>
135 <pre>
136 USAGE: {utest|ptest|mtest} [args...] [test name...]
137 </pre>
138
139 <p>Now we can edit configuration by selecting <b>Run</b> &rarr; <b>Debug Configurations...</b> and pass additional
140 parameters to unit testing subsystem. Select the generated <b>lsp-plugins</b> debug profile, <b>Arguments</b> tab
141 and enter testing subsystem command-line arguments. For example, the following:</p>
142 <pre>
143 mtest --nofork --debug standalone --args impulse_reverb_stereo
144 </pre>
145 <p>It will look like:</p>
146 <div class="images">
147 <img src="<?= $IMG ?>eclipse-cpp-debug.png">
148 </div>
149
150 <p>Now click <b>Apply</b> and <b>Debug</b> buttons to start debugging. The example command line will start a standalone
151 <b>Impulse Reverb Stereo</b> plugin that runs under JACK server:</p>
152 <div class="images">
153 <img class="border" src="<?= $IMG ?>eclipse-mtest-plugin.png">
154 </div>
155
156 <p>Happy Development!</p>