diff options
Diffstat (limited to 'doc/api/HowToAddProgrammingLanguages.dox')
| -rw-r--r-- | doc/api/HowToAddProgrammingLanguages.dox | 252 |
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. + + +*/ |