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, 252 insertions, 0 deletions

diff --git a/doc/api/HowToAddProgrammingLanguages.dox b/doc/api/HowToAddProgrammingLanguages.dox
new file mode 100644
index 00000000..5cfa3643
--- /dev/null
+++ b/doc/api/HowToAddProgrammingLanguages.dox
@@ -0,0 +1,252 @@
+/** \file HowToAddProgrammingLanguages.dox
+  * \brief How to add support for a programming language
+  */
+
+/** \page howToAddProgrammingLanguages How to add support for a programming language
+
+\section LSupport List of things to have "complete" support of a given language in KDevelop
+
+  - Implement interface KDevLanguageSupport
+  - \ref sectionClassWizard
+  - \ref sectionAttributeMethodWizard
+  - \ref sectionQtUiSubclassing - (if the language has Qt bindings)
+  - \ref sectionLanguageParser
+  - \ref sectionClassStore
+    - \ref sectionMemoryClassStore
+    - \ref sectionPersistantClassStore
+    .
+  - \ref sectionCodeCompletion
+  - \ref sectionProblemReporter - (parses source on the fly and reports syntax errors)
+  - \ref sectionTemplates
+    - \ref sectionApplicationTemplates
+    - \ref sectionApplicationImportTemplates
+    - \ref sectionSourceFileTemplates
+    - \ref sectionAbbreviationTemplates - (ife expands to an if else statement, etc)
+    .
+  - \ref sectionSourceCodeFormater (prettyprint functionality)
+  - \ref sectionDocumentationTopics
+  - \ref sectionDebugger
+    - (gdb/jdb/??? integration)
+  - \ref sectionCompilerPlugins
+  .
+
+List of optional things to support a given language in KDevelop:
+  - \ref sectionEditor - Syntax highlighter - (add to QEditor if not available elsewhere)
+  - \ref sectionBuildTool (make/ant/etc)
+  .
+
+Take a look at \ref LangSupportStatus (doc/api/LangSupportStatus.dox file) to see the current status/features of the programming languages currently supported by KDevelop.
+
+
+
+
+\section sectionLanguageSupport Language Support
+
+Any language support should be written as a kdevelop part and implement
+KDevLanguageSupport interface (<code>lib/interfaces/kdevlanguagesupport.h</code>).
+
+Implementing methods:
+ - <code>virtual Features features();</code>
+ - <code>virtual KMimeType::List mimeTypes();</code>
+ .
+
+Should be enough for a language support to start working.
+
+KDevelop ships with KDevLang project template. It is a simple language support prototype that can be used when developing language support plugins with KDevelop.
+To use it, start a New Project and select: <code>C++->KDevelop->KDevelop Language Support Plugin</code> in the application wizard.
+The template is located in <code>languages/cpp/app_templates/kdevlang</code>, you can change it there if you need.
+
+
+You should look at <code>languages/ruby</code> for a simple language support
+implementation. For a compilable language support, consult <code>languages/ada</code> or <code>languages/pascal</code> (they are not so complex as <code>languages/cpp</code>).
+
+Pascal would be a good starting place, as it is the smaller of the two by far.
+
+Language support can offer additional features:
+
+\subsection sectionClassWizard Class wizard
+  - new class wizard: (See <code>ada, php, cpp</code> or <code>java</code>)
+    - <code>virtual void addClass();</code>
+    .
+
+\subsection sectionAttributeMethodWizard Attribute/Method wizard
+  - add method dialog: (See <code>cpp</code> or <code>java</code>)
+    - <code>virtual void addMethod(const QString &className);</code>
+    .
+  - add attribute dialog: (See <code>cpp</code> or <code>java</code>)
+    - <code>virtual void addAttribute(const QString &className);</code>
+    .
+  .
+
+\subsection sectionQtUiSubclassing Qt UI subclassing
+
+If there is a Qt bindings for your language and there is a possibility
+to use QtDesigner ui files, you could implement ui subclassing feature:
+  - <code>virtual QStringList subclassWidget(const QString& formName);</code>
+  - <code>virtual QStringList updateWidget(const QString& formName, const QString&
+        fileName);</code>
+  .
+
+See <code>cpp</code> and <code>java</code> for examples.
+
+\subsection sectionLanguageParser Language parser
+
+In general, class stores can be filled with information without specialized
+and complex language parsers (take a look at <code>languages/python</code> that have a very simple python parser) but your language support will surely benefit
+from having such. There is a hand-written c/c++ parser (<code>lib/cppparser</code>) in KDevelop that might be used for ObjC or related C-based languages.
+
+Other (not so complex as c++) languages can be parsed by ANTLR based parsers (library is in lib/antlr).
+Consult www.antlr.org for a ANTLR documentation and look at <code>languages/java</code>, <code>languages/ada</code> and <code>languages/pascal</code> for an example of using such parsers.
+The latest version of ANTLR (2.7.2) has support for Java, C, Pascal, Ada, C++, CIM, HTML, IDL, Verilog, VRML, OCL, ASN.1, and SQL. You can write an ANTLR parser for your own language, of course.
+
+\subsection sectionClassStore Class store
+
+If you write (or have) a language parser, your language support can have
+"class store" (a database containing the information about scopes, classes
+and methods - their names, names of source files, location in source files,
+etc.). Class store libraries can be found at <code>lib/catalog</code> (Catalog) and <code>lib/interfaces</code> (CodeModel).
+
+KDevelop provides class browsers that extract information from a <b>class store</b> and display it in a tree view and toolbar selectors of scopes, classes and methods.
+
+\subsubsection sectionMemoryClassStore Memory class store
+CodeModel is the memory class store. It is very efficient and thus it is recommended for using as a project class store. CodeModel libraries are located in <code>lib/interfaces/codemodel.h</code>. The class browser for a CodeModel based stores is <code>parts/classview</code>.
+
+\subsubsection sectionPersistantClassStore Persistant class store
+Catalog is the persistant class store for KDevelop. Persistant class store can be used as an information storage for code completion but it also can be used as a class store for the project. Take a look at
+<code>languages/cpp</code> for an example of using catalog. Catalog is stored on disk in the database file (Berkeley db) If you use catalog with the project, your class browser will be <code>parts/classbrowser</code>.
+
+\subsection sectionCodeCompletion Code completion
+Class store enables you to write a code completion for the language. At the
+moment (2003-06-25), code completion is available only to cpp so take a
+look at it for an example.
+
+\subsection sectionProblemReporter Problem reporter
+
+If you have a language parser, you can implement <b>problem reporter</b>
+functionality for your language. The problem reporter catches errors
+reported by a parser and displays it in a problem reporter view.
+<code>languages/java</code>, <code>languages/ada</code>, <code>languages/pascal</code> and <code>languages/cpp</code> have problem reporters.
+
+\subsection sectionTemplates Templates
+
+\subsubsection sectionApplicationTemplates Application templates
+
+<b>Application wizard</b> templates should be also written. Appwizard templates are simple to create - consult \ref howToAddApplicationTemplates (HowToAddApplicationTemplates.dox file)
+and look at <code>languages/ruby/app_templates/rubyhello</code>, <code>languages/pascal/app_templates/pascalhello</code>, or <code>languages/ada/app_templates/adahello</code>.
+
+\subsubsection sectionApplicationImportTemplates Application import templates
+
+KDevelop has the ability to <b>create a new project from existing projects or source code</b>.
+It scans for project files ('*.kdevelop, *.kdevprj, *.studio, *.pro) and if
+  - it finds a project it extracts the necessary information
+  - it does not find project files it scans for source files (*.cpp, *.java, *.pl, *.py, ...)
+  .
+and creates a new KDevelop project in the direcotry the user has chosen.
+
+\subsubsection sectionSourceFileTemplates Source file templates
+
+Another thing to do is to create <b>file create templates</b>. They are prototypes for a source files of your language. These prototypes are placed in
+<code>parts/filecreate/file-templates</code> dir or <code>languages/YOURLANGUAGE/file_templates</code> and have names equal to the extensions of language source files.
+The description of the prototypes is placed in <code>parts/filecreate/template-info.xml</code>.
+
+Consult FileCreatePart (parts/filecreate/README.dox file) and \ref howToAddFileTemplates for further information.
+
+\subsubsection sectionAbbreviationTemplates Code abbreviation templates
+
+KDevelop has a support for <b>code abbreviations</b> so you can add some predefined abbreviations to your language support. Take <code>languages/cpp/cpptemplates</code> as an example.
+
+
+\subsection sectionSourceCodeFormater Source code formater
+
+Implement a KDevSourceFormater class interface.
+To obtain source formater functionality (that is already available to
+c-based languages) you can extend astyle library (<code>lib/astyle</code>) that is used by KDevelop to format sources.
+Take a look at AStylePart for an example how to do it.
+
+\subsection sectionDocumentationTopics Documentation topics
+
+Add them to <code>languages/YOURLANGUAGE/doc</code>. For an example see <code>languages/python/doc/python.toc</code> and <code>languages/python/doc/python.index</code>
+In the end you need to edit the <code>languages/YOURLANGUAGE/doc/Makefile.am</code> file to include the .toc and/or .index file.
+
+\subsection sectionDebugger Debugger
+
+The last thing to have a complete language support in KDevelop is to
+write a <b>Debugger </b>. KDevelop already provides GDB support
+(<code>languages/cpp/debugger</code>) and JDB (java debugger) support (<code>languages/java/debugger</code>). Take a look at them to get inspiration.
+
+\subsection sectionCompilerPlugins Compiler plugins
+
+There is an ability to create compiler plugin for KDevelop. Compiler plugin provides the compiler configuration dialog which implements command line compiler options.
+Compiler plugins must implement KDevCompilerOptions interface.
+
+
+\section MiscInf Other Info
+
+In the end you should add the language you implemented to the doc/api/LangSupportStatus.dox file and
+document your language support part in the way described at \ref howToDocument (doc/api/HowToDocument.dox file).
+See also \ref howToAddPlugins (doc/api/HowToAddPlugins.dox file) for an information on how to create a generic KDevelop plugin and how to manage project and global configuration information.
+
+
+
+
+
+\section sectionEditor Language Editor
+
+To edit source files KDevelop uses any editor that supports the KTextEditor
+interface. The current supported editors and their features are listed
+in the \ref EditorsSupportStatus (doc/api/EditorsSupportStatus.dox file) page.
+
+In case none of the editors does support advanced editing of sources
+written in your language (like code folding, syntax highlighting, line
+indentation) you can improve QEditor included in KDevelop (<code>editors/qeditor</code>).
+By creating QEditorIndenter and QSourceColorizer descendants you can provide the support for an automatic indentation and syntax highlighting that will be available for sure in KDevelop.
+
+
+
+
+
+
+\section sectionBuildTool Build Tool
+
+The language support is important, but it is unusable without a <b>build tool</b>
+that can manage projects written on this language. KDevelop
+currently provides several build tools. They are:
+
+  - ANT build tool
+    - see AntProjectPart at <code>buildtools/ant</code>
+    .
+  - Autotools build tool
+    - see AutoProjectPart at <code>buildtools/autotools</code>
+    .
+  - Custom build tool
+    - see CustomProjectPart at <code>buildtools/custommakefiles</code>
+    - (works with custom makefiles, also has ant support)
+    .
+  - Generic build tool
+    - see GenericProjectPart at <code>buildtools/generic</code>
+    - Offers build tool facilities using project files in xml format (dtd is located in <code>buildtools/generic/kdevxmlproject.dtd</code>).
+      Those xml files can be converted into makefiles, ant xml files or simply shell scripts using build system plugins.
+      Build system plugin is an object that implements KDevBuildSystem interface. Build system plugins are located in <code>buildtools/generic/buildsystem</code>.
+    .
+  - QMake build tool
+    - see TrollProjectPart at <code>buildtools/qmake</code>
+    .
+  .
+
+Also available:
+  - Script build tool
+    - <code>buildtools/script</code>
+    - (the generic build tool for all scripting languages).
+    .
+  - <code>buildtools/pascal</code> and
+  - <code>buildtools/ada</code>
+  - <code>buildtools/haskell</code>
+  .
+
+(They are deprecated build tools that will be replaced with the generic build tool).
+
+Choose your build tool and if the existing build tools doesn't fit
+in, extend generic build tool via build system plugin. \ref howToAddGenericBuildTools page (doc/api/HowToAddGenericBuildTools.dox file) helps you to do it.
+
+
+*/