summaryrefslogtreecommitdiffstats
path: root/doc/kdevelop/project-management.docbook
blob: 756742039904e3e7efffac54e689f60000b7ad8b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
<chapter id="project-management">

<chapterinfo>
  <authorgroup>
    <author><firstname>Bernd</firstname><surname>Pol</surname></author>
    <author><firstname>Ian</firstname><surname>Wadham</surname></author>
    <!-- ROLES_OF_TRANSLATORS -->
  </authorgroup>
</chapterinfo>

<title>Building and Project Management</title>

<para>
This chapter deals only with compiled projects, such as C++, &Java; or
Fortran projects. Projects for scripting languages like Python and
PHP work very differently.
</para>

<para>
You will find here information on:</para>
<itemizedlist>
  <listitem><para>
  <link linkend="automake-manager-summary">Summary of &automanag;</link> containing an initial overall view of &automanag;,
  </para></listitem>
  <listitem><para>
  <link linkend="automake-manager-operation">Automake Manager Operation</link> describing the basics of how to work with &automanag;,
  </para></listitem>
</itemizedlist>

<sect1 id="automake-manager-summary">
<title>Summary of &automanag;</title>

<para>
In the <link linkend="unixdev-buildsystems">Build systems</link> chapter we have given a rough overview of the build systems commonly in use on &UNIX; systems. In the following sections we will look at this in more detail.
</para>
<para>
There is some confusion about how to name such things. &GNU; calls them <quote>build systems</quote> when it describes Automake, Autoconf and Libtool. QMake calls itself <quote>a tool to write Makefiles for different compilers and platforms</quote>. In &kde; often the term <quote>project management systems</quote> is used. We will use this term in a broader sense to describe the built-in environments in &kdevelop; which are used to organize and build your projects. In the context of this section, however, we will mostly talk about <quote>automated build systems</quote>.
</para>

<sect2 id="automake-manager-summary-buildsys">
<title>The Need for an Automated Build System</title>

<para>
If you have a simple <quote>Hello World</quote> program, written in C, you can compile and link it using &gcc; <parameter>-o hello hello.c</parameter> and execute it using the command <command>./hello</command>, so you do not even need a <filename>Makefile</filename>.
</para>
<para>
If you have a C application with several modules and header files and you are only going to run it on your own machine (&ie; it is an in-house application), you will only need a simple <filename>Makefile</filename>, which is fairly easy to write by hand (use <userinput>info make</userinput> to find out more).
</para>
<para>
The complications begin when:
</para>
<itemizedlist>
  <listitem><para>
  Your source-code, documentation, graphics, sounds, translations, data files, &etc; are located in more than one directory,
  </para></listitem>
  <listitem><para>
  You have a hierarchy of directories and sub-directories,
  </para></listitem>
  <listitem><para>
  You are using libraries that are not part of the traditional &UNIX; set, such as the &Qt; Object Library or the &kde; Desktop libraries,
  </para></listitem>
  <listitem><para>
  You are using a pre-processor to generate some of your source-code, such as Qt's MOC pre-compiler,
  </para></listitem>
  <listitem><para>
  You aim to distribute your application worldwide, to people who may not have the same &UNIX;/&Linux; system, software and hardware as you,
  </para></listitem>
  <listitem><para>
  You require an automated Install and Uninstall facility,
  </para></listitem>
  <listitem><para>
  You aim to make your application part of the &kde; Desktop set.
  </para></listitem>
</itemizedlist>

<para>
If you have some or all of the above situations, you probably need a <emphasis>build system</emphasis>. In the example above we used &gcc; to compile and build the <quote>Hello World</quote> program, but not all C compilers are called <quote>&gcc;</quote>. So if you distribute your application to someone who is using some other C compiler, your Makefile must somehow use the name of that person's compiler, otherwise your application will fail to compile&mdash;and that is just simple example of what can go wrong.
</para>
<para>
A build system will iron out these differences for you.
</para>
<itemizedlist>
  <listitem><para>
  It will check that the libraries you need are present on each receiving machine,
  </para></listitem>
  <listitem><para>
  will automatically scan all your application directories for files to pre-process, compile or install and
  </para></listitem>
  <listitem><para>
  will install the components of your application in the correct receiving directories, making sure that
  </para></listitem>
  <listitem><para>
  the directories are created in the receiving machine as required.
  </para></listitem>
</itemizedlist>

<para>
In brief, a build system offers safe and secure methods for your application to be compiled and installed correctly on any receiving machine. As we have shown before in the <link linkend="makesystems">Project Management Systems</link> survey, &kdevelop; offers three automated build systems and the option of creating your own Makefile, in short (click on the project names to get more information):
</para>
<itemizedlist>
  <listitem><para>
  <link linkend="automake-project">Automake projects</link> which use the &GNU; standard development tools.
  </para></listitem>
  <listitem><para>
  <link linkend="qmake-project">QMake projects</link> which use the trolltech QMake project manager.
  </para></listitem>
  <listitem><para>
  <link linkend="ant-project">ANT projects</link> which use the Apache ANT project manager for &Java; development.
  </para></listitem>
  <listitem><para>
  <link linkend="custom-project">Custom projects</link> which require you to maintain your own <filename>Makefiles</filename>.
  </para></listitem>
</itemizedlist>

<important>
<para>
One of these four alternatives must be chosen when you create a project and <emphasis>the choice is difficult to change later</emphasis>, so you should give it some thought before you start.
</para>
</important>

</sect2> <!--  automake-manager-summary-buildsys -->

<sect2 id="automake-references">
<title>Tutorials on Autoconf/Automake/Libtool</title>
<para>
There are several tutorials available on the &GNU; Build System (<command>Autoconf</command>, <command>Automake</command> and <command>Libtool</command>) of which the &automanag; makes use.
</para>
<itemizedlist>
  <listitem><para>A short <ulink url="http://www.kdevelop.org/index.html?filename=tutorial_autoconf.html">autoconf tutorial</ulink> written by Christopher W. Curtis available on the &kdevelop; home page. It concentrates on some basic steps to modify a <filename>Makefile</filename>.
  </para></listitem>
  <listitem><para>
  A more detailed tutorial can be found in a greater set of tutorials on  <ulink url="http://www.amath.washington.edu/~lf/tutorials/autoconf/toolsmanual_toc.html"><quote>Developing software with GNU</quote></ulink>.
  </para></listitem>
  <listitem><para>
  And there is the famous <ulink url="http://sources.redhat.com/autobook"><quote>Goat Book</quote></ulink>, titled <quote>Autoconf, Automake, and Libtool</quote>. This is an easily readable, yet concise, introduction in all main aspects of the &GNU; Autotools.
  </para></listitem>
</itemizedlist>

</sect2> <!--  automake-references -->

<sect2 id="automake-manager-basics">
<title>What does &automanag; Do?</title>

<para>
The <link linkend="applicationwizard">&appwizard;</link> will have set up some initial <filename>Makefile.am</filename> files when you created a <guilabel>New Project</guilabel> of a type that uses the &GNU; Build System, such as <menuchoice><guimenuitem>C++</guimenuitem> <guimenuitem>KDE</guimenuitem> <guimenuitem>Application framework</guimenuitem></menuchoice>. During development &automanag; creates any other <filename>Makefile.am</filename> files for projects that use the &GNU; Build System and maintains them all, &appwizard; and &automanag; created alike.
</para>
<para>
There will be one <filename>Makefile.am</filename> file in each directory of your project that contains files to be compiled or installed. It will contain your specifications for compiling, building and installing files and a reference to any subdirectories that also have a <filename>Makefile.am</filename> file and possibly some files to compile, build and install.
</para>

<note><para>
Your project's directories and source files may be structured to any depth, or you may prefer a flat project-structure with all subdirectories at the top level.
</para></note>

<para>
The aim of the &GNU; Build System is to produce source-code file structures that can be compiled, built and installed on any &UNIX; or &Linux; system by using the simple commands:
</para>

<screen>
./configure
make
make install    # Usually as "root".
</screen>

<para>and can be uninstalled by the command <command>make uninstall</command> (usually as root).
</para>

<para>
How does this work? Well <command>configure</command> is a script that

<itemizedlist>
  <listitem><para>
  works out the details of whatever system it is in, such as what compiler and libraries to use and where they are located, and then
  </para></listitem>
  <listitem><para>
  creates recursive <filename>Makefile</filename> files by filling in the substitutions in the corresponding <filename>Makefile.in</filename> files.
  </para></listitem>
</itemizedlist>
</para>
<para>
The <filename>Makefile.in</filename> are <quote>input</quote> files&mdash;templates which provide basic information for the <filename>Makefile</filename>s to be produced from them by filling in some system dependent information. They are generated by the <command>Automake</command> utility from the <filename>Makefile.am</filename> files.
</para>
<para>
The process of going from <filename>Makefile.am</filename> (<filename>.am</filename> denotes <quote>Automake</quote> template files) to <filename>Makefile</filename> files is handled automatically by the &kdevelop; &promanag;, using the <command>Autoconf</command> utility, <command>M4</command> macros and other arcana we need not go into here.
</para>
<para>
So when <command>make</command> runs, it automatically picks up the correct pieces from the current environment, such as compilers and libraries. Similarly, <command>make install</command> puts your application components, such as executables, documentation and data files in the correct places for that environment.
</para>

<para>
If you distribute your application as a <quote>tarball</quote> (a single compressed file that &kdevelop; can create for you), it will include the <filename>Makefile.in</filename> files and the <filename>configure</filename> script file, so the recipient can compile, build and install your application without having <command>Automake</command>, <command>Autoconf</command> or &kdevelop; on their machine. The <filename>Makefile.am</filename> files are also included, just in case the receiver needs to do any source-code modifications.
</para>
<note><para>
The rules are rather different if you distribute via a web-based source-code repository such as &kde; &cvs;.
</para></note>

</sect2> <!--  automake-manager-basics -->

<sect2 id="automake-manager-basics-summary">
<title>Summary of What Automake Manager Does</title>

<itemizedlist>
  <listitem><para>
  Generates <filename>Makefile.am</filename> files in subdirectories it knows as <quote>subprojects</quote>.
  </para></listitem>
  <listitem><para>
  Updates <filename>Makefile.am</filename> files as the project structure changes.
  </para></listitem>
  <listitem><para>
  Updates <filename>Makefile.am</filename> files as files are added to or removed from the project.
  </para></listitem>
  <listitem><para>
  Accepts definitions of how the various files are to be built or installed and modifies the <filename>Makefile.am</filename> accordingly.
  </para></listitem>
  <listitem><para>
  Accepts parameters used in building or installing (&eg; library names) and ensures that they are used in the required compilation and build steps.
  </para></listitem>
</itemizedlist>

</sect2> <!--  automake-manager-basics-summary -->

<sect2 id="automake-file-contents">
<title>Contents of Automake Files</title>

<para>
A <filename>Makefile.am</filename> file has lines containing variable-names followed by an equals sign and a list of files or parameter values. The <quote>variables</quote> have two-part names, such as <varname>bin_PROGRAMS</varname>, <varname>myapp_SOURCES</varname> or <varname>kdelnk_DATA</varname>. The second part is called the <emphasis>primary</emphasis> and represents something from which to build or install. The first part is called the <emphasis>prefix</emphasis> and represents:
</para>
<itemizedlist>
  <listitem><para>
  A <emphasis>directory</emphasis> in which to do installation (&eg; <filename>bin</filename>),
  </para></listitem>
  <listitem><para>
  A <emphasis>qualifier</emphasis> for the primary (&eg; <varname>myapp</varname> for <varname>SOURCES</varname>, indicating that the source files listed after <varname>myapp_SOURCES</varname> go into building <filename>myapp</filename>),
  </para></listitem>
  <listitem><para>
  A special <emphasis>prefix</emphasis> <varname>noinst</varname> (short for <quote>no installation</quote>), usually used to list program header files (<filename>.h</filename>),
  </para></listitem>
  <listitem><para>
  Or the special prefix <varname>EXTRA</varname>, for <emphasis>configuration-dependent</emphasis> stuff.
  </para></listitem>
</itemizedlist>

<para>
For more information on <command>Automake</command> and <filename>Makefile.am</filename> files, look up <userinput>info Automake</userinput>.
</para>
<para>
Basically, &automanag; creates and updates the variable-names and lists of files or parameters. See the following example of a <filename>Makefile.am</filename> for a typical application, called <filename>myapp</filename>.
</para>

<screen>
## Makefile.am for myapp

# this is the program that gets installed.  it's name is used for all
# of the other Makefile.am variables
bin_PROGRAMS = myapp

# set the include path for X, qt and KDE
INCLUDES = $(all_includes)

# the library search path.
myapp_LDFLAGS = $(KDE_RPATH) $(all_libraries)

# the libraries to link against.
myapp_LDADD   = $(LIB_KFILE) $(LIB_TDEPRINT)

# which sources should be compiled for myapp
myapp_SOURCES = main.cpp myapp.cpp myappview.cpp

# these are the headers for your project
noinst_HEADERS = myapp.h myappview.h

# let automoc handle all of the meta source files (moc)
METASOURCES = AUTO

KDE_ICON = myapp

# this is where the kdelnk file will go
kdelnkdir = $(kde_appsdir)/Utilities
kdelnk_DATA = myapp.desktop

# this is where the XML-GUI resource file goes
rcdir = $(kde_datadir)/myapp
rc_DATA = myappui.rc

AM_CXXFLAGS = -DMY_C++_PREPROCESSOR_OPTION
</screen>

<para>
As you can see, many of the items on the right hand side are symbols of the form <varname>$(xxx)</varname>. These are <emphasis>environment variables</emphasis> which are defined in the actual &kde; environment and are substituted with real values when <command>./configure</command> generates the final <filename>Makefile</filename> files in the receiving machine.
</para>

<para>
Also, sometime after you have started with &kdevelop;, it is a good idea to run the command <command>./configure --help</command>, which will show you the range of things you can change at build and installation time, such as for a test environment. In particular, the command:

<screen>
./configure --prefix=/where/you/wish
</screen>
will re-direct the entire installation to a directory structure of your choice, by changing the internal variable <varname>$(prefix)</varname> to value <filename class="directory">/where/you/wish</filename>.
</para>

</sect2> <!-- automake-file-contents -->

</sect1> <!--  automake-manager-summary -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="automake-manager-operation">
<title>Automake Manager Operation</title>

<para>
In this chapter you will find a basic description of the &automanag; elements and how to use them. This covers:
<itemizedlist>
  <listitem><para>
  <link linkend="automake-manager-operation-window">The &automanag; Window</link> describes the basic structure of the &automanag; main window.
  </para></listitem>
  <listitem><para>
  <link linkend="automake-manager-operation-survey-window">The Overall View Window</link> describes the elements of the upper subwindow.
  </para></listitem>
  <listitem><para>
  <link linkend="automake-manager-operation-detail-window">The Detail View Window</link> describes the elements of the lower subwindow.
  </para></listitem>
  <listitem><para>
  <link linkend="automake-manager-operation-navigate">Navigating in the &automanag;</link> lists some basic operations you can perform in the &automanag;.
  </para></listitem>
  <listitem><para>
  <link linkend="automake-manager-operation-popups">Popup Menus in the &automanag;</link> describes the windows which will pop up when you select an action in the &automanag;.
  </para></listitem>
</itemizedlist>
</para>

<sect2 id="automake-manager-operation-window">
<title>The &automanag; Window</title>

<informaltable frame="none">
<tgroup cols="2"><tbody><row>
  <entry><inlinemediaobject>
    <imageobject>
      <imagedata fileref="automakemanager.png" format="PNG"/>
    </imageobject>
  </inlinemediaobject></entry>
  <entry valign="top"><itemizedlist>
    <listitem><para>
    &automanag; runs in a split window. The top part is called the <emphasis>Overall View</emphasis> and the bottom part is called the <emphasis>Detail View</emphasis>. Between them is a narrow bar that can be dragged with the mouse to adjust the sizes of the views. In IDEAl mode you can also drag the side of the split window to change the width.
    </para></listitem>
    <listitem><para>
    On top of each view there is a <emphasis>toolbar</emphasis>, the buttons in which will become activated when an element in this view is selected. This provides one way you can access the actions provided for that view element. The other are context menus which pop up on right mouse button click as will be discussed below.
    </para></listitem>
    <listitem><para>
    In IDEAl mode there are two additional small buttons in the &automanag; window titlebar left hand side &ndash; a triangular shaped right arrow, and a dot button. The arrow button is used to <emphasis>close the window</emphasis>. The dot button on the other hand will <emphasis>keep the window open</emphasis> even if another &kdevelop; window has been selected. (Otherwise the &automanag; window will automatically close whenever another window gets the input focus.)
    </para></listitem>
  </itemizedlist></entry>
</row></tbody></tgroup>
</informaltable>

</sect2> <!-- automake-manager-operation-window -->

<sect2 id="automake-manager-operation-survey-window">
<title>The Overall View Window</title>

<para>
The overall view window contains a tree-list of all the directories in your project that contain program files, documentation or data. Each such directory contains a <filename>Makefile.am</filename> file and is known in &automanag; as a <emphasis>subproject</emphasis>. There are three typical subprojects in a &kde;-based project as shown in the above illustration:
</para>

<itemizedlist>
  <listitem><para>
  <filename>src</filename> &ndash; source-code files for your application,
  </para></listitem>
  <listitem><para>
  <filename>doc</filename> &ndash; your user manual or Handbook,
  </para></listitem>
  <listitem><para>
  <filename>po</filename> &ndash; extracts of strings in your source-code files that require translation into other human languages (&eg; window titles, menu names, button labels, dialog box text and messages of various kinds).
  </para></listitem>
</itemizedlist>

<para>
Note that the <filename>doc</filename> subproject always has an <filename>en</filename> subproject, which you can see if you click on the <symbol>+</symbol> symbol next to the word <filename>doc</filename>. That is because the base language of all documentation in &kde; is  United States English (en). If your application becomes part of &kde;, the &kde; translation teams may translate your documentation from United States English into other languages and the translations will go into other subprojects, such as <filename>de</filename> (German) or <filename>fr</filename> (French). The strings in the <filename>po</filename> subproject may also be translated and stored in other files in <filename>po</filename>, thus allowing your application to be operated by people who do not know English.
</para>

<note><para>
The <filename>doc</filename> and <filename>po</filename> subprojects serve different purposes. <filename>doc</filename> contains <emphasis>documentation</emphasis> like a user manual, <filename>po</filename> contains translatable text strings of the <emphasis>user interface</emphasis> which is integrated in the source code of this application.
</para></note>

<para>
The overall view window serves&mdash;amongst other things&mdash;as a navigation tool. If you select a subproject in the overall view window, the corresponding details will be shown in the detail view window.
</para>

</sect2> <!-- automake-manager-operation-survey-window -->

<sect2 id="automake-manager-operation-detail-window">
<title>The Detail View Window</title>

<para>
The detail view contains a tree-list of all the files in the subproject currently selected in the overall view as well as the compilation, build and installation rules for this subproject. Thus the two views together can give you access to all the components of your application and all the information on how to compile, build and install it.
</para>

<sect3>
<title>Targets</title>

<para>The tree-list in the detail view has two levels. The top level consists of so-called &automanag; <emphasis>targets</emphasis> and the next level contains lists of files that go to make up each target.
</para>

<para>
This concept of an &automanag; target differs somewhat from what a <filename>Makefile</filename> target usually is. In short:</para>
<itemizedlist>
  <listitem><para>
  The definition of how a set of files is to be compiled, built or installed is known as a <emphasis>target</emphasis> in &automanag;, but as a <emphasis>variable</emphasis> in <command>Automake</command> itself.
  </para></listitem>
  <listitem><para>
  A <emphasis>target</emphasis> in <command>make</command> is often something quite different, being the parameter of a <command>make</command> command (&eg; <userinput>make install</userinput>, <userinput>make clean</userinput>).
  </para>
  <para>
  However some <filename>Makefile.am</filename> variables do represent an underlying <emphasis>sub-target</emphasis> in <command>make</command>.
  </para></listitem>
</itemizedlist>

</sect3>
</sect2> <!-- automake-manager-operation-detail-window -->

<sect2 id="automake-manager-operation-navigate">
<title>Navigating in the &automanag;</title>

<para>
In both the overall and the detail view you can left-click on the <symbol>+</symbol> or <symbol>-</symbol> next to a subproject or target name to expand or contract the tree view. If you do that with a <emphasis>subproject</emphasis> in the overall view, it shows or hides the subprojects at the next level down (if any). If you do it with a <emphasis>target</emphasis> in the detail view, it shows or hides the list of files that go into that target.
</para>

<variablelist>
<varlistentry>
<term>Opening a file for Edit</term>
<listitem>
<para>If you <emphasis>&LMB; click</emphasis> on a file name in the detail
view, the corresponding file opens up in &kdevelop;'s editing window.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>Activating the &automanag; Toolbar Buttons</term>
<listitem>
<para>
If you <emphasis>&LMB; click</emphasis> on the name of a subproject in the
overall view or target in the detail view, the name is highlighted and some
toolbar buttons become active in the top part of that view.</para>

<note>
  <para>
  It is recommended that you use the <emphasis>right mouse-button and popup menus</emphasis>, rather than the toolbar buttons, because it is then much easier to see and understand what you are doing.
  </para>
  <para>
  Operations on subprojects and targets have far-reaching effects on the structure, compilation, building and installation of your application.
  </para>
</note>
</listitem>
</varlistentry>

<varlistentry>
<term>Selecting Actions/Popup Menus</term>
<listitem>
<para>
If you <emphasis>&RMB; click</emphasis> on the name of a subproject, target or file, a menu pops up and you can then select actions to perform on the subproject, target or file, such as add a target to the subproject, add a file to a target or logically remove the selected file from its target.
</para>
</listitem>
</varlistentry>
</variablelist>

</sect2> <!-- automake-manager-operation-navigate -->

<sect2 id="automake-manager-operation-popups">
<title>Popup Menus in the &automanag;</title>

<para>
The following sections explain in short terms which operations the menus make available which will pop up on right mouse button clicks in the &automanag; window. They are meant for overall view only. You will find detailed descriptions of most operations in a later chapter.
</para>
<!-- ### add a link to this chapter when ready -->

<sect3 id="automake-manager-operation-popups-file">
<title>The Popup Menu for a File</title>

<para>
When you &RMB; click on a <emphasis>file name</emphasis> in the detail view the following menu will pop up allowing you to select one of several operations to be performed on that file. In the illustration below the <filename>hi-16app-myapp.png</filename> icon file was selected from the <guilabel>Icon data in myapp</guilabel> target of the <guilabel>myapp/src</guilabel> subproject.
</para>

<informaltable frame="none">
<tgroup cols="2"><tbody><row>
  <entry><inlinemediaobject>
    <imageobject>
      <imagedata fileref="automake-file-popup.png" format="PNG"/>
    </imageobject>
  </inlinemediaobject></entry>
  <entry valign="bottom"><itemizedlist>
    <listitem><para>
    The main popup-menu item for a file is to <guimenuitem>Remove</guimenuitem> the file from its target (&ie; it will no longer be used to compile, build or install that target).
    </para></listitem>
    <listitem><para>
    The <guimenuitem>CVS</guimenuitem> item offers a variety of CVS operations on the file.
    </para></listitem>
    <listitem><para>
    The <guimenuitem>Open With</guimenuitem> item allows you to open the file with a variety of editors or with any application at all (&eg; you can open the icon file in our example with <application>KIcon</application>).
    </para></listitem>
    <listitem><para>
    The <guimenuitem>Perforce</guimenuitem> item is used for similar operations as in CVS using the commercial <quote><application>Perforce</application></quote> version control system.
    </para></listitem>
  </itemizedlist></entry>
</row></tbody></tgroup>
</informaltable>

</sect3> <!-- automake-manager-operation-popups-file -->

<sect3 id="automake-manager-operation-popups-target">
<title>The Popup Menu for a Target</title>

<para>
When you right-click on a <emphasis>target</emphasis> in the detail view the following menu will pop up allowing you to select one of several operations to be performed on it. In the illustration below the <guilabel>myapp (Program in bin)</guilabel> target of the <guilabel>myapp/src</guilabel> subproject was selected.
</para>

<informaltable frame="none">
<tgroup cols="2"><tbody><row>
  <entry><inlinemediaobject>
    <imageobject>
      <imagedata fileref="automake-target-popup.png" format="PNG"/>
    </imageobject>
  </inlinemediaobject></entry>
  <entry valign="bottom"><itemizedlist>
    <listitem><para>
    The <guimenuitem>Options</guimenuitem> item for a target only applies to source code files. In the corresponding dialog box you can specify linker flags and paths on which to locate libraries and you can give a list of actual libraries to be linked in to your application.
    </para></listitem>
    <listitem><para>
    The <guimenuitem>Create New File</guimenuitem> item brings up a dialog in which you can set the file name and the type of file to be generated (from a drop-down list).
    </para></listitem>
    <listitem><para>
    The <guimenuitem>Add Existing Files</guimenuitem> item brings up a dialog box in which you can add an already existing file to this target.
    </para></listitem>
    <listitem><para>
    The <guimenuitem>Remove</guimenuitem> item for a target allows you to logically remove the target and all its files from the project structure.
    </para></listitem>
    <listitem><para>
    The <guimenuitem>Make Target Active</guimenuitem> item only applies to targets containing source code files. New files will always be added to such an active target.
    </para></listitem>
    <listitem><para>
    The <guimenuitem>Build Target</guimenuitem> item calls all necessary compile and make operations to build the code for this target only.
    </para></listitem>
  </itemizedlist></entry>
</row></tbody></tgroup>
</informaltable>

</sect3> <!-- automake-manager-operation-popups-target -->

<sect3 id="automake-manager-operation-popups-subproject">
<title>The Popup Menu for a Subproject</title>

<para>
When you &RMB; click on a <emphasis>subproject</emphasis> in the overall view window the following menu will pop up which allows you to make major changes to the structure of your project and the way it is compiled, built and installed. You can use it to expand or modify the basic project structure that the &appwizard; has created.
</para>


<informaltable frame="none">
<tgroup cols="2"><tbody><row>
  <entry><inlinemediaobject>
    <imageobject>
      <imagedata fileref="automake-subproject-popup.png" format="PNG"/>
    </imageobject>
  </inlinemediaobject></entry>
  <entry valign="bottom"><itemizedlist>
    <listitem><para>
    The <guimenuitem>Options</guimenuitem> item for a subproject controls the way that the subproject will be compiled, built and installed. The dialog box that pops up has tabs for Compiler, Includes, Prefixes and Build Order.
    </para></listitem>
    <listitem><para>
    The <guimenuitem>Add Subproject</guimenuitem> item creates a new directory and skeleton Makefile.am file.
    </para></listitem>
    <listitem><para>
    The <guimenuitem>Add Target</guimenuitem> item pops up a dialog in which you can set the rules for compiling, building or installing a group of files within your subproject.
    </para></listitem>
    <listitem><para>
    <guimenuitem>Add Service</guimenuitem> (... to be written ...)
    </para></listitem>
    <listitem><para>
    <guimenuitem>Add Application</guimenuitem> (... to be written ...)
    </para></listitem>
    <listitem><para>
    <guimenuitem>Add Existing Subprojects</guimenuitem> (... to be written ...)
    </para></listitem>
    <listitem><para>
    The <guimenuitem>Remove Subproject</guimenuitem> item in the popup menu for a subproject is the proper way to remove a subproject. It will adjust the <filename>Makefile.am</filename> files accordingly. You will also be offered the option to delete all the files (or links) in the corresponding subdirectory. Obviously, this feature should be used with caution.
    </para></listitem>
    <listitem><para>
    The <guimenuitem>Build</guimenuitem> item calls all necessary compile and make operations to build the code for this subproject only.
    </para></listitem>
    <listitem><para>
    <guimenuitem>Force Reedit</guimenuitem> (... to be written ...)
    </para></listitem>
    <listitem><para>
    <guimenuitem>Clean</guimenuitem> (... to be written ...)
    </para></listitem>
    <listitem><para>
    <guimenuitem>Install</guimenuitem> (... to be written ...)
    </para></listitem>
    <listitem><para>
    <guimenuitem>Install (as root user)</guimenuitem> (... to be written ...)
    </para></listitem>
  </itemizedlist></entry>
</row></tbody></tgroup>
</informaltable>

</sect3> <!-- automake-manager-operation-popups-subproject -->

</sect2> <!-- automake-manager-operation-popups -->

</sect1> <!-- automake-manager-operation -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="autoproject">
<title>Automake Projects</title>
<indexterm zone="autoproject"><primary><command>autoproject</command></primary></indexterm>
<indexterm zone="autoproject"><primary>&automake;</primary></indexterm>
<indexterm zone="autoproject"><primary>&autoconf;</primary></indexterm>
<indexterm zone="autoproject"><primary>&libtool;</primary></indexterm>

<para>
(... to be written ...)
</para>


<sect2 id="autoconf">
<title>Autoconf</title>
<indexterm zone="autoconf"><primary><filename>configure</filename> script</primary></indexterm>
<indexterm zone="autoconf"><primary><filename>config.status</filename> script</primary></indexterm>
<indexterm zone="autoconf"><primary><filename>Makefile.in</filename></primary></indexterm>
<indexterm zone="autoconf"><primary><filename>config.h.in</filename></primary></indexterm>

<para>
<filename>Makefile.in</filename> into <filename>Makefile</filename>
</para>

<programlisting>
prefix = @prefix@
INSTALL = @INSTALL@
build_triplet = @build@
CXX = @CXX@
</programlisting>

<programlisting>
prefix = /home/bernd/trinity
INSTALL = /usr/bin/ginstall -c -p
build_triplet = i686-pc-linux-gnu
CXX = g++
</programlisting>

<para>
<filename>config.h.in</filename> into <filename>config.h</filename>
</para>

<programlisting>
/* Define if you have libz */
#undef HAVE_LIBZ
/* The size of a `int', as computed by sizeof. */
#undef SIZEOF_INT
</programlisting>

<programlisting>
/* Define if you have libz */
#define HAVE_LIBZ 1
/* The size of a `int', as computed by sizeof. */
#define SIZEOF_INT 4
</programlisting>

</sect2> <!-- autoconf -->


<sect2 id="automake">
<title>Automake</title>

<para>
(... to be written ...)
</para>

</sect2> <!--automake  -->


<sect2 id="automake-manager">
<title>&kdevelop;'s &automanag;</title>

<figure id="screenshot-automake-manager" float="1">
<title>A screenshot of the automake manager</title>
<mediaobject>
<imageobject><imagedata fileref="automake-manager.png"/></imageobject>
</mediaobject>
</figure>

</sect2> <!-- automake-manager -->


<sect2 id="automakelibrary">
<title>Building and Installing Libraries</title>

<para>
<itemizedlist>
<listitem><para>
  -rpath
</para></listitem>
<listitem><para>
  PIC
</para></listitem>
<listitem><para>
  static
</para></listitem>
<listitem><para>
  plugins: no-undefined
</para></listitem>
</itemizedlist>
</para>

</sect2> <!-- automakelibrary -->

</sect1> <!-- autoproject -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="customproject">
<title>Custom Makefiles and Build Scripts</title>
<indexterm zone="customproject"><primary><filename>Makefile</filename></primary></indexterm>
<indexterm zone="customproject"><primary><filename>build.xml</filename></primary></indexterm>

<para>
(... to be written ...)
</para>

</sect1> <!-- customproject -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="compileroptions">
<title>Compiler Options</title>

<para>
(... to be written ...)
</para>

</sect1> <!-- compileroptions -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="makeoptions">
<title>Make Options</title>

<para>
(... to be written ...)
</para>

</sect1> <!-- makeoptions -->

</chapter> <!-- project-management -->