Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdevelop@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 386 insertions, 0 deletions

diff --git a/doc/kdevelop/unixdev.docbook b/doc/kdevelop/unixdev.docbook
new file mode 100644
index 00000000..d7881afb
--- /dev/null
+++ b/doc/kdevelop/unixdev.docbook
@@ -0,0 +1,386 @@
+<appendix id="unixdev">
+
+<appendixinfo>
+  <authorgroup>
+    <author><firstname>Bernd</firstname><surname>Pol</surname></author>
+    <!-- ROLES_OF_TRANSLATORS -->
+  </authorgroup>
+</appendixinfo>
+
+<title>Development on &UNIX;</title>
+
+<indexterm zone="unixdev"><primary>development</primary></indexterm>
+<indexterm zone="unixdev">
+  <primary>&UNIX;</primary>
+  <secondary>development</secondary></indexterm>
+
+<sect1 id="history">
+<title>Some Historical Remarks</title>
+
+<indexterm zone="history"><primary>history</primary></indexterm>
+<indexterm zone="history"><primary>scripting languages</primary></indexterm>
+<indexterm zone="history">
+  <primary>&UNIX;</primary>
+  <secondary>history</secondary></indexterm>
+<indexterm zone="history">
+  <primary>&UNIX;</primary>
+  <secondary>pipe</secondary></indexterm>
+<indexterm zone="history">
+  <primary>&UNIX;</primary>
+  <secondary>shell</secondary></indexterm>
+<indexterm zone="history">
+  <primary>shell</primary>
+  <secondary>&UNIX;</secondary></indexterm>
+
+<para>
+From the beginning, &UNIX; has maintained two very different development paradigms. One is the world of <emphasis>system and application programming languages</emphasis>, where some source code is translated to machine code by a translation program, usually a <emphasis>compiler</emphasis> or an <emphasis>interpreter</emphasis>. The programming language C is an example. &UNIX; was the first operating system kernel to be written in such a high level language instead of tightly machine-oriented assembler which was common before that time. (In fact, the C language once even was invented to write the &UNIX; kernel and associated programs on a DEC PDP-11 computer.)
+</para>
+<para>
+The other paradigm is the world of <emphasis>scripting languages</emphasis>. This world evolved with the invention of the &UNIX; shell which was the user's interface to the operating system&mdash;and at the same time a very high level programming language. A shell script is built from a set of small utility programs like &eg; <command>grep</command>, <command>sed</command>, or <command>find</command>. Each such utility is designed for some tightly defined job. The trick is that any such utility can be connected to another one via a simple transport mechanism, called a <emphasis>pipe</emphasis>, which directs the output of the foregoing utility into the input of the next processed one. This makes for a very powerful and highly flexible programming tool.
+</para>
+<para>
+As time has gone by, both worlds have evolved. While C is still used mainly as a system programming language, C++ as a variant of C enriched by object-oriented and generic extensions has found its place for the development of complex applications in the 1990's. There are numerous other programming languages, even older ones keep their place&mdash;FORTRAN77 and Ada &eg; still have their stronghold in numerical applications.
+</para>
+</sect1> <!-- history -->
+
+<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
+
+<sect1 id="unixdev-scripting-languages">
+<title>Contemporary Scripting Languages</title>
+<para>
+In the scripting area, there has been a shift away from the shell, which suffers from portability concerns, to languages which unify all commonly needed functionality in their standard libraries, while still being able to interface to the outside through pipes when necessary.
+</para>
+<para>
+All these scripting languages have in common that they are widely portable between &UNIX; variants, Microsoft &Windows;, &MacOS; or even VMS. Also, they all have implementations that are freely distributable.
+</para>
+
+<sect2 id="unixdev-SL-Perl">
+<title>&perl;</title>
+
+<indexterm zone="unixdev-SL-Perl"><primary>Perl</primary></indexterm>
+<indexterm zone="unixdev-SL-Perl">
+  <primary>scripting languages</primary>
+  <secondary>Perl</secondary></indexterm>
+
+<para>
+<ulink url="http://www.perl.com">&perl;</ulink> has become popular as a text processing and system administration language. In the beginning of the World Wide Web, CGI scripts written in &perl; were a widely used method to create dynamic web pages from databases. Today, this method has been replaced mostly by the <command>mod_perl</command> plugin for the &apache; web server. Among &perl;'s strengths are its built-in support for advanced regular expression matching and its rich archive of freely distributed modules.
+</para>
+<para>
+For more information see the <ulink url="http://cpan.org">Comprehensive Perl Archive Network (<acronym>CPAN</acronym>)</ulink> website.
+</para>
+</sect2> <!-- unixdev-SL-Perl -->
+
+<sect2 id="unixdev-SL-Python">
+<title>Python</title>
+
+<indexterm zone="unixdev-SL-Python"><primary>Python</primary></indexterm>
+<indexterm zone="unixdev-SL-Python">
+  <primary>scripting languages</primary>
+  <secondary>Python</secondary></indexterm>
+
+<para>
+<ulink url="http://www.python.org">&python;</ulink> shines by the elegance of its class system and the ease and flexibility with which external libraries can be wrapped in a way that they appear like standard &python; classes and functions. In contrast to &perl;, &python; has a clear and concise embedding &API;, which makes it the language of choice for making C and C++ programs scriptable.
+</para>
+</sect2> <!-- unixdev-SL-Python -->
+
+<sect2 id="unixdev-SL-PHP">
+<title>PHP</title>
+
+<indexterm zone="unixdev-SL-PHP"><primary>PHP</primary></indexterm>
+<indexterm zone="unixdev-SL-PHP">
+  <primary>scripting languages</primary>
+  <secondary>PHP</secondary></indexterm>
+
+<para>
+<ulink url="http://www.php.net">&php;</ulink> was invented as a language directly embeddable into &HTML; pages and consequently has its main uses in delivering dynamic content on the web.
+</para>
+</sect2> <!-- unixdev-SL-PHP -->
+</sect1> <!-- unixdev-scripting-languages -->
+
+<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
+<sect1 id="unixdev-hl-script">
+<title>Higher-level Scripting</title>
+
+<para>
+Higher-level &UNIX; applications usually miss the speed and flexibility of the traditional character-oriented shell scripting mechanisms. This is especially true in the world of graphical user interfaces (&GUI;) such as &eg; &kde;.
+</para>
+<para>
+There have been attempts to provide similar mechanisms which will work on a higher application level, most notably <link linkend="unixdev-corba">CORBA</link> and, in the &kde; environment, <link linkend="unixdev-dcop">&DCOP;</link>.
+</para>
+
+<sect2 id="unixdev-corba">
+<title>The CORBA Protocol</title>
+
+<indexterm zone="unixdev-corba"><primary>CORBA</primary></indexterm>
+<indexterm zone="unixdev-corba">
+  <primary>scripting languages</primary>
+  <secondary>CORBA</secondary></indexterm>
+<indexterm zone="unixdev-corba">
+  <primary>communication</primary>
+  <secondary>CORBA</secondary></indexterm>
+
+<para>
+<ulink url="http://www.omg.org/gettingstarted/corbafaq.htm">CORBA</ulink> (<emphasis>Common Object Request Broker Architecture</emphasis>) is an attempt to let computer applications work together over networks. It was devised by the private, vendor independent <ulink url="http://www.omg.org">OMG</ulink> (Object Management Group) standards comittee.
+</para>
+<para>
+CORBA-based programs use the IIOP standard protocol to communicate. Implementations based on IIOP are available on a wide variety of operating systems, programming languages, and networks and are thus highly portable.
+</para>
+<para>
+The main drawback of CORBA is its rather low speed. While this may be tolerable in networks, it is a real hindrance for inter-application communications in a non-networked environment such as &kde; running on a single computer.
+</para>
+
+</sect2> <!-- unixdev-corba -->
+
+<sect2 id="unixdev-dcop">
+<title>The &DCOP; Interface</title>
+
+<indexterm zone="unixdev-dcop"><primary>DCOP</primary></indexterm>
+<indexterm zone="unixdev-dcop">
+  <primary>scripting languages</primary>
+  <secondary>DCOP</secondary></indexterm>
+<indexterm zone="unixdev-dcop">
+  <primary>communication</primary>
+  <secondary>DCOP</secondary></indexterm>
+
+<para>
+Another evolution on &UNIX;-like scripting is the <ulink url="http://developer.kde.org/documentation/library/kdeqt/dcop.html"><emphasis>DCOP</emphasis></ulink> protocol which was devised for communication between &kde; applications to overcome the limitations of CORBA.
+</para>
+<para>
+&DCOP; stands for <emphasis>Desktop Communication Protocol</emphasis> and is implemented as a simple IPC/RPC mechanism built to operate over sockets. In effect this provides facilities similar to the traditional &UNIX; pipe mechanism.
+</para>
+<para>
+Traditional shell scripting is based on fairly small tool programs which were designed to work on a strictly textual basis. &DCOP; allows elaborate graphical programs to communicate with each other in a quite similar way. This enables &eg; a &kde; program to send messages to another &kde; program, or receive data from it for its own purposes.
+</para>
+<para>
+There are drawbacks, however. To use &DCOP; a program must be designed to contain a special &DCOP; interface. And the &DCOP; communication process runs somewhat slowly (although a lot faster than CORBA). But it returns much of the power and flexibility of &UNIX; scripting to high-level programs which are based on a graphical user interface.
+</para>
+<para>
+For more information, see the <ulink url="http://developer.kde.org/documentation/library/kdeqt/dcop.html">DCOP: Desktop COmmunications Protocol</ulink> paper or <ulink url="developer.kde.org/documentation/library/cvs-api/dcop/html/index.html">The &DCOP; Desktop Communication Protocol library</ulink> &API; reference of the &kde; dcop library.
+</para>
+</sect2> <!--  unixdev-dcop -->
+
+</sect1> <!--  unixdev-hl-script -->
+
+<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
+
+<sect1 id="unixdev-buildsystems">
+<title>Build Systems</title>
+
+<para>
+Except in very simple cases a programming project will consist of a lot of building blocks of source code each put into a separate file for easier maintenance. To make this running one has to effectively translate all this stuff into a few machine language units in a suiting format which allows the operating system to load and execute the program.
+</para>
+<para>
+To accomplish this, the basic tools needed are
+<itemizedlist>
+  <listitem><para>
+  a <emphasis>text editor</emphasis> to write the source code files,
+  </para></listitem>
+  <listitem><para>
+  a translating program, usually a <emphasis>compiler</emphasis> to turn the source code into object files,
+  </para></listitem>
+  <listitem><para>
+  a <emphasis>librarian</emphasis> which collects object files into libraries to reuse them easily without the need to recompile,
+  </para></listitem>
+  <listitem><para>
+  a <emphasis>linker</emphasis> which binds several object files and libraries together into one executable,
+  </para></listitem>
+  <listitem><para>
+  a <emphasis>make system</emphasis> which provides some means to manage all this stuff and&mdash;not to forget
+  </para></listitem>
+  <listitem><para>
+  a <emphasis>debugger</emphasis> to (hopefully) find all errors in the program and possibly some other diagnostic tools to get everything running smoothly.
+  </para></listitem>
+</itemizedlist>
+</para>
+
+<para>
+When you have a large project consisting of possibly hundreds of source code files, the process of compiling may become quite laborsome. You do not want to recompile all files each time you have changed only some of them. Instead, you only want to compile those files which are affected by the changes. In general, it is not always easily obvious which of the files have to be recompiled.
+</para>
+<para>
+When you &eg; change a function prototype in a header file, you need to compile every file which includes this header file. If your project contains many such files you may easily miss one or two of them if you have to do the job manually. Thus some means of automization is necessary.
+</para>
+
+<sect2 id="unixdev-buildsystems-make">
+<title>The Make Process</title>
+
+<indexterm zone="unixdev-buildsystems-make">
+  <primary>make</primary></indexterm>
+<indexterm zone="unixdev-buildsystems-make">
+  <primary>Makefile</primary></indexterm>
+<indexterm zone="unixdev-buildsystems-make">
+  <primary>rule</primary></indexterm>
+<indexterm zone="unixdev-buildsystems-make">
+  <primary>recompilations</primary></indexterm>
+<indexterm zone="unixdev-buildsystems-make">
+  <primary>target</primary></indexterm>
+<indexterm zone="unixdev-buildsystems-make">
+  <primary>dependencies</primary></indexterm>
+<indexterm zone="unixdev-buildsystems-make">
+  <primary>commands</primary></indexterm>
+
+<para>
+A tool which takes care of recompilations is <command>make</command>. It keeps track of all work using a set of <emphasis>rules</emphasis> which describe what to do in case some piece of information (usually a source or object code file) was changed. All rules belonging to a certain project are stored in a so-called <filename>Makefile</filename> which is processed by <command>make</command> any time you want to update your work.
+</para>
+<para>
+Each rule consists of several building blocks, namely
+<itemizedlist>
+  <listitem><para>
+  a <emphasis>target</emphasis>, &ie; the file to be built
+  </para></listitem>
+  <listitem><para>
+  a set of <emphasis>dependencies</emphasis>, basically the names of those files the target depends on (&eg; the name of a source file, where then the target will be the name of the object file to be built) and
+  </para></listitem>
+  <listitem><para>
+  the <emphasis>commands</emphasis> which are to be executed to <quote>make</quote> the target (&ie; to compile it or to link other object files together to build an executable progam file).
+  </para></listitem>
+</itemizedlist>
+</para>
+<para>
+Basically the <command>make</command> command will read the rules one after another, check each file in the dependency list of a given target and make this target anew if any one of these files has changed, using the commands listed in that rule.
+</para>
+<para>
+There are several additional possibilities to control such a make process, and a <filename>Makefile</filename> can thus grow very complex. We cannot go into the details here. However, we recommend that you make yourself accustomed to the syntax of <command>make</command>. Even if you do not normally use it directly, an understanding of the fundamentals of the build system can be useful. See the <ulink url="info://make/Top"> <quote>GNU Make Manual</quote></ulink> for more information. </para>
+<para>
+For more &kdevelop; specific detail see the <link  linkend="project-management">Building and Project Management</link> chapter of this manual.
+</para>
+<para>
+There are several tutorials available, see the <link linkend="automake-references">references</link> in the Building and project management chapter.
+</para>
+</sect2> <!-- unixdev-buildsystems-make -->
+
+</sect1> <!-- unixdev-buildsystems -->
+
+<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
+
+<sect1 id="unixdev-guidevelopment">
+<title>&GUI; Development</title>
+
+<indexterm zone="unixdev-guidevelopment">
+  <primary>GUI</primary></indexterm>
+<indexterm zone="unixdev-guidevelopment">
+  <primary>graphical user interface</primary></indexterm>
+<indexterm zone="unixdev-guidevelopment">
+  <primary>user interface</primary>
+  <secondary>GUI</secondary></indexterm>
+
+<para>
+Application developers become even more encumbered by having not only to create program libraries and logic, but also to provide an easy to use custom built user interface that is both intuitive and functional.  Most programmers receive little to no training in &GUI; development, and as a result user interfaces often are poorly designed.
+</para>
+<para>
+During the years some common design principles have evolved. It is strongly advised to adhere to them. This way your user interfaces will retain a common look and feel that the users of your application will gratefully appreciate.
+</para>
+<para>
+For &kde; &GUI; development there is a style guide available. It is found in the <ulink url="http://developer.kde.org/documentation/standards/kde/style/basics/index.html">&kde; User Interface Guidelines</ulink> on the &kde; Developer's Corner page.
+</para>
+<para>
+A short introduction to common &GUI; design principles can be found <ulink url="http://axp16.iie.org.mx/Monitor/v01n03/ar_ihc2.htm">here</ulink>.
+</para>
+
+</sect1> <!-- unixdev-guidevelopment -->
+
+<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
+
+<sect1 id="unixdev-ide">
+<title>Integrating Concepts and Tools &ndash; the IDE</title>
+
+<indexterm zone="unixdev-ide">
+  <primary>IDE</primary></indexterm>
+<indexterm zone="unixdev-ide">
+  <primary>integrated development environment</primary></indexterm>
+<indexterm zone="unixdev-ide">
+  <primary>development</primary>
+  <secondary>IDE</secondary></indexterm>
+<indexterm zone="unixdev-ide">
+  <primary>environment</primary>
+  <secondary>IDE</secondary></indexterm>
+
+<para>
+There are separate tools available for almost any step in the programming process&mdash;planning, editing, managing files and compilation processes, debugging, documentation and the like. But once the projects grow the programming processes will most likely become quite cumbersome.
+</para>
+<para>
+Much repetitive work has to be done when designing, compiling, and debugging a program. A lot of such work can be saved through the use of templates and scripts. And another lot by keeping these tools easily available and able to communicate with each other under a common &GUI;.
+</para>
+<para>
+For example&mdash;would it not be convenient if a debugger were able to open the source file in question in an editor and place the cursor directly at the position of that bug just found?
+</para>
+<para>
+To more easily accomplish such a scheme, <emphasis>Integrated Development Environments</emphasis> (&IDE;s) were devised. Such an &IDE; integrates all templates, tools, and scripts which are commonly needed in the development process into one single environment.
+</para>
+<para>
+For the &kde; platform &kdevelop; is such an &IDE;. It provides a wide range of tools which ease program development and maintenance, even for different programming languages and across platforms.
+</para>
+
+<sect2 id="unixdev-ide-kdevelop">
+<title>Basic Features of &kdevelop; &kdevrelease;</title>
+
+<indexterm zone="unixdev-ide-kdevelop">
+  <primary>&kdevelop;</primary>
+  <secondary>features</secondary></indexterm>
+<indexterm zone="unixdev-ide-kdevelop">
+  <primary>features</primary></indexterm>
+
+<!-- ### copied from web page, needs to be updated -->
+
+<itemizedlist>
+  <listitem>
+  <para>Manages all <emphasis>development tools</emphasis> needed for C++ programming, such as compiler, linker, debugger and build system.</para>
+  </listitem>
+  <listitem>
+  <para>Provides an <emphasis>&appwizard;</emphasis> which generates complete, ready-to-go sample applications.</para>
+  </listitem>
+  <listitem>
+  <para>Allows the user to select an <emphasis>integrated editor</emphasis> based on the &kde; programmer's editor &kwrite;, Trolltec's <application>QEditor</application>, or others.</para>
+  </listitem>
+  <listitem>
+  <para>A <emphasis>class generator</emphasis>, for creating new classes and integrating them into the current project.</para>
+  </listitem>
+  <listitem>
+  <para><emphasis>File management</emphasis> for sources, headers, documentation &etc; to be included in the project.</para>
+  </listitem>
+  <listitem>
+  <para>Assistance in <emphasis>creating application user manuals</emphasis> written with &kde; tools.</para>
+  </listitem>
+  <listitem>
+  <para>Automatic &HTML; based <emphasis>&API; documentation</emphasis> for a project's classes with cross-references to the used libraries.</para>
+  </listitem>
+  <listitem>
+  <para><emphasis>Internationalization support</emphasis>, allowing translators to add their target language to a project easily, including support for &kbabel;.</para>
+  </listitem>
+  <listitem>
+  <para>Support for managing a project via one of several <emphasis>versioning systems</emphasis> (&eg; &CVS;) by providing an easy-to-use frontend for the most needed functions.</para>
+  </listitem>
+  <listitem>
+  <para>An integrated <emphasis>debugger</emphasis> frontend.</para>
+  </listitem>
+  <listitem>
+  <para>An integrated <emphasis>shell console</emphasis> emulator.</para>
+  </listitem>
+  <listitem>
+  <para><emphasis>Syntax highlighting</emphasis> in source texts.</para>
+  </listitem>
+  <listitem>
+  <para>An <emphasis>auto-code completion</emphasis> facility for class variables, class methods, function arguments and more.</para>
+  </listitem>
+  <listitem>
+  <para><emphasis>Templates for creating various projects</emphasis> (&kcontrol; modules, &kicker; (panel) applets, KIOSlaves, &konqueror; plugins and desktop styles).</para>
+  </listitem>
+  <listitem>
+  <para>Four <emphasis>navigation tree views</emphasis> for easily switching between source files, header files, classes and documentation, obviating the need for an external file manager.</para>
+  </listitem>
+  <listitem>
+  <para><emphasis>Cross-compiling support</emphasis>, with the ability to specify different compilers, compiler flags, target architecture, &etc;</para>
+  </listitem>
+  <listitem>
+  <para>Support for <emphasis>Qt/Embedded projects</emphasis> (such as the Zaurus and iPAQ).</para>
+  </listitem>
+  <listitem>
+  <para><emphasis>Inclusion of any other program</emphasis> you need for development by adding it to the <guimenuitem>Tools</guimenuitem> menu according to your individual needs.</para>
+  </listitem>
+</itemizedlist>
+
+</sect2> <!-- unixdev-ide-kdevelop -->
+
+</sect1> <!-- unixdev-ide -->
+
+</appendix> <!-- unixdev -->
+