/** \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 tdevelop 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 ('*.tdevelop, *.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.


*/