diff options
Diffstat (limited to 'Documentation/development')
| -rw-r--r-- | Documentation/development/Doxyfile | 1780 | ||||
| -rw-r--r-- | Documentation/development/coding-style-policy.md | 800 | ||||
| -rw-r--r-- | Documentation/development/compiling.md | 413 | ||||
| -rw-r--r-- | Documentation/development/road-map.md | 834 | ||||
| -rw-r--r-- | Documentation/development/stable-release-policy.md | 80 |
5 files changed, 3907 insertions, 0 deletions
diff --git a/Documentation/development/Doxyfile b/Documentation/development/Doxyfile new file mode 100644 index 0000000..37b6522 --- /dev/null +++ b/Documentation/development/Doxyfile @@ -0,0 +1,1780 @@ + +# Doxyfile 1.8.2 + +# This file describes the settings to be used by the documentation system +# doxygen (www.doxygen.org) for a project. +# +# All text after a hash (#) is considered a comment and will be ignored. +# The format is: +# TAG = value [value, ...] +# For lists items can also be appended using: +# TAG += value [value, ...] +# Values that contain spaces should be placed between quotes (" "). + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- + +# This tag specifies the encoding used for all characters in the config file +# that follow. The default is UTF-8 which is also the encoding used for all +# text before the first occurrence of this tag. Doxygen uses libiconv (or the +# iconv built into libc) for the transcoding. See +# http://www.gnu.org/software/libiconv for the list of possible encodings. + +DOXYFILE_ENCODING = UTF-8 + +# The PROJECT_NAME tag is a single word (or sequence of words) that should +# identify the project. Note that if you do not use Doxywizard you need +# to put quotes around the project name if it contains spaces. + +PROJECT_NAME = "KiCad Developer's Resource Documentation" + +# The PROJECT_NUMBER tag can be used to enter a project or revision number. +# This could be handy for archiving the generated documentation or +# if some version control system is used. + +PROJECT_NUMBER = + +# Using the PROJECT_BRIEF tag one can provide an optional one line description +# for a project that appears at the top of each page and should give viewer +# a quick idea about the purpose of the project. Keep the description short. + +PROJECT_BRIEF = + +# With the PROJECT_LOGO tag one can specify an logo or icon that is +# included in the documentation. The maximum height of the logo should not +# exceed 55 pixels and the maximum width should not exceed 200 pixels. +# Doxygen will copy the logo to the output directory. + +PROJECT_LOGO = + +# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) +# base path where the generated documentation will be put. +# If a relative path is entered, it will be relative to the location +# where doxygen was started. If left blank the current directory will be used. + +OUTPUT_DIRECTORY = doxygen + +# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create +# 4096 sub-directories (in 2 levels) under the output directory of each output +# format and will distribute the generated files over these directories. +# Enabling this option can be useful when feeding doxygen a huge amount of +# source files, where putting all generated files in the same directory would +# otherwise cause performance problems for the file system. + +CREATE_SUBDIRS = NO + +# The OUTPUT_LANGUAGE tag is used to specify the language in which all +# documentation generated by doxygen is written. Doxygen will use this +# information to generate all constant output in the proper language. +# The default language is English, other supported languages are: +# Afrikaans, Arabic, Brazilian, Catalan, Chinese, Chinese-Traditional, +# Croatian, Czech, Danish, Dutch, Esperanto, Farsi, Finnish, French, German, +# Greek, Hungarian, Italian, Japanese, Japanese-en (Japanese with English +# messages), Korean, Korean-en, Lithuanian, Norwegian, Macedonian, Persian, +# Polish, Portuguese, Romanian, Russian, Serbian, Serbian-Cyrillic, Slovak, +# Slovene, Spanish, Swedish, Ukrainian, and Vietnamese. + +OUTPUT_LANGUAGE = English + +# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will +# include brief member descriptions after the members that are listed in +# the file and class documentation (similar to JavaDoc). +# Set to NO to disable this. + +BRIEF_MEMBER_DESC = YES + +# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend +# the brief description of a member or function before the detailed description. +# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the +# brief descriptions will be completely suppressed. + +REPEAT_BRIEF = YES + +# This tag implements a quasi-intelligent brief description abbreviator +# that is used to form the text in various listings. Each string +# in this list, if found as the leading text of the brief description, will be +# stripped from the text and the result after processing the whole list, is +# used as the annotated text. Otherwise, the brief description is used as-is. +# If left blank, the following values are used ("$name" is automatically +# replaced with the name of the entity): "The $name class" "The $name widget" +# "The $name file" "is" "provides" "specifies" "contains" +# "represents" "a" "an" "the" + +ABBREVIATE_BRIEF = + +# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then +# Doxygen will generate a detailed section even if there is only a brief +# description. + +ALWAYS_DETAILED_SEC = NO + +# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all +# inherited members of a class in the documentation of that class as if those +# members were ordinary class members. Constructors, destructors and assignment +# operators of the base classes will not be shown. + +INLINE_INHERITED_MEMB = YES + +# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full +# path before files name in the file list and in the header files. If set +# to NO the shortest path that makes the file name unique will be used. + +FULL_PATH_NAMES = NO + +# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag +# can be used to strip a user-defined part of the path. Stripping is +# only done if one of the specified strings matches the left-hand part of +# the path. The tag can be used to show relative paths in the file list. +# If left blank the directory from which doxygen is run is used as the +# path to strip. Note that you specify absolute paths here, but also +# relative paths, which will be relative from the directory where doxygen is +# started. + +STRIP_FROM_PATH = + +# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of +# the path mentioned in the documentation of a class, which tells +# the reader which header file to include in order to use a class. +# If left blank only the name of the header file containing the class +# definition is used. Otherwise one should specify the include paths that +# are normally passed to the compiler using the -I flag. + +STRIP_FROM_INC_PATH = + +# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter +# (but less readable) file names. This can be useful if your file system +# doesn't support long names like on DOS, Mac, or CD-ROM. + +SHORT_NAMES = NO + +# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen +# will interpret the first line (until the first dot) of a JavaDoc-style +# comment as the brief description. If set to NO, the JavaDoc +# comments will behave just like regular Qt-style comments +# (thus requiring an explicit @brief command for a brief description.) + +JAVADOC_AUTOBRIEF = YES + +# If the QT_AUTOBRIEF tag is set to YES then Doxygen will +# interpret the first line (until the first dot) of a Qt-style +# comment as the brief description. If set to NO, the comments +# will behave just like regular Qt-style comments (thus requiring +# an explicit \brief command for a brief description.) + +QT_AUTOBRIEF = NO + +# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen +# treat a multi-line C++ special comment block (i.e. a block of //! or /// +# comments) as a brief description. This used to be the default behaviour. +# The new default is to treat a multi-line C++ comment block as a detailed +# description. Set this tag to YES if you prefer the old behaviour instead. + +MULTILINE_CPP_IS_BRIEF = NO + +# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented +# member inherits the documentation from any documented member that it +# re-implements. + +INHERIT_DOCS = YES + +# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce +# a new page for each member. If set to NO, the documentation of a member will +# be part of the file/class/namespace that contains it. + +SEPARATE_MEMBER_PAGES = NO + +# The TAB_SIZE tag can be used to set the number of spaces in a tab. +# Doxygen uses this value to replace tabs by spaces in code fragments. + +TAB_SIZE = 4 + +# This tag can be used to specify a number of aliases that acts +# as commands in the documentation. An alias has the form "name=value". +# For example adding "sideeffect=\par Side Effects:\n" will allow you to +# put the command \sideeffect (or @sideeffect) in the documentation, which +# will result in a user-defined paragraph with heading "Side Effects:". +# You can put \n's in the value part of an alias to insert newlines. + +ALIASES = + +# This tag can be used to specify a number of word-keyword mappings (TCL only). +# A mapping has the form "name=value". For example adding +# "class=itcl::class" will allow you to use the command class in the +# itcl::class meaning. + +TCL_SUBST = + +# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C +# sources only. Doxygen will then generate output that is more tailored for C. +# For instance, some of the names that are used will be different. The list +# of all members will be omitted, etc. + +OPTIMIZE_OUTPUT_FOR_C = NO + +# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java +# sources only. Doxygen will then generate output that is more tailored for +# Java. For instance, namespaces will be presented as packages, qualified +# scopes will look different, etc. + +OPTIMIZE_OUTPUT_JAVA = NO + +# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran +# sources only. Doxygen will then generate output that is more tailored for +# Fortran. + +OPTIMIZE_FOR_FORTRAN = NO + +# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL +# sources. Doxygen will then generate output that is tailored for +# VHDL. + +OPTIMIZE_OUTPUT_VHDL = NO + +# Doxygen selects the parser to use depending on the extension of the files it +# parses. With this tag you can assign which parser to use for a given +# extension. Doxygen has a built-in mapping, but you can override or extend it +# using this tag. The format is ext=language, where ext is a file extension, +# and language is one of the parsers supported by doxygen: IDL, Java, +# Javascript, CSharp, C, C++, D, PHP, Objective-C, Python, Fortran, VHDL, C, +# C++. For instance to make doxygen treat .inc files as Fortran files (default +# is PHP), and .f files as C (default is Fortran), use: inc=Fortran f=C. Note +# that for custom extensions you also need to set FILE_PATTERNS otherwise the +# files are not read by doxygen. + +EXTENSION_MAPPING = + +# If MARKDOWN_SUPPORT is enabled (the default) then doxygen pre-processes all +# comments according to the Markdown format, which allows for more readable +# documentation. See http://daringfireball.net/projects/markdown/ for details. +# The output of markdown processing is further processed by doxygen, so you +# can mix doxygen, HTML, and XML commands with Markdown formatting. +# Disable only in case of backward compatibilities issues. + +MARKDOWN_SUPPORT = YES + +# When enabled doxygen tries to link words that correspond to documented classes, +# or namespaces to their corresponding documentation. Such a link can be +# prevented in individual cases by by putting a % sign in front of the word or +# globally by setting AUTOLINK_SUPPORT to NO. + +AUTOLINK_SUPPORT = YES + +# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want +# to include (a tag file for) the STL sources as input, then you should +# set this tag to YES in order to let doxygen match functions declarations and +# definitions whose arguments contain STL classes (e.g. func(std::string); v.s. +# func(std::string) {}). This also makes the inheritance and collaboration +# diagrams that involve STL classes more complete and accurate. + +BUILTIN_STL_SUPPORT = NO + +# If you use Microsoft's C++/CLI language, you should set this option to YES to +# enable parsing support. + +CPP_CLI_SUPPORT = NO + +# Set the SIP_SUPPORT tag to YES if your project consists of sip sources only. +# Doxygen will parse them like normal C++ but will assume all classes use public +# instead of private inheritance when no explicit protection keyword is present. + +SIP_SUPPORT = NO + +# For Microsoft's IDL there are propget and propput attributes to indicate getter and setter methods for a property. Setting this option to YES (the default) will make doxygen replace the get and set methods by a property in the documentation. This will only work if the methods are indeed getting or setting a simple type. If this is not the case, or you want to show the methods anyway, you should set this option to NO. + +IDL_PROPERTY_SUPPORT = YES + +# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC +# tag is set to YES, then doxygen will reuse the documentation of the first +# member in the group (if any) for the other members of the group. By default +# all members of a group must be documented explicitly. + +DISTRIBUTE_GROUP_DOC = NO + +# Set the SUBGROUPING tag to YES (the default) to allow class member groups of +# the same type (for instance a group of public functions) to be put as a +# subgroup of that type (e.g. under the Public Functions section). Set it to +# NO to prevent subgrouping. Alternatively, this can be done per class using +# the \nosubgrouping command. + +SUBGROUPING = YES + +# When the INLINE_GROUPED_CLASSES tag is set to YES, classes, structs and +# unions are shown inside the group in which they are included (e.g. using +# @ingroup) instead of on a separate page (for HTML and Man pages) or +# section (for LaTeX and RTF). + +INLINE_GROUPED_CLASSES = NO + +# When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and +# unions with only public data fields will be shown inline in the documentation +# of the scope in which they are defined (i.e. file, namespace, or group +# documentation), provided this scope is documented. If set to NO (the default), +# structs, classes, and unions are shown on a separate page (for HTML and Man +# pages) or section (for LaTeX and RTF). + +INLINE_SIMPLE_STRUCTS = NO + +# When TYPEDEF_HIDES_STRUCT is enabled, a typedef of a struct, union, or enum +# is documented as struct, union, or enum with the name of the typedef. So +# typedef struct TypeS {} TypeT, will appear in the documentation as a struct +# with name TypeT. When disabled the typedef will appear as a member of a file, +# namespace, or class. And the struct will be named TypeS. This can typically +# be useful for C code in case the coding convention dictates that all compound +# types are typedef'ed and only the typedef is referenced, never the tag name. + +TYPEDEF_HIDES_STRUCT = NO + +# Similar to the SYMBOL_CACHE_SIZE the size of the symbol lookup cache can be +# set using LOOKUP_CACHE_SIZE. This cache is used to resolve symbols given +# their name and scope. Since this can be an expensive process and often the +# same symbol appear multiple times in the code, doxygen keeps a cache of +# pre-resolved symbols. If the cache is too small doxygen will become slower. +# If the cache is too large, memory is wasted. The cache size is given by this +# formula: 2^(16+LOOKUP_CACHE_SIZE). The valid range is 0..9, the default is 0, +# corresponding to a cache size of 2^16 = 65536 symbols. + +LOOKUP_CACHE_SIZE = 6 + +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- + +# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in +# documentation are documented, even if no documentation was available. +# Private class members and static file members will be hidden unless +# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES + +EXTRACT_ALL = YES + +# If the EXTRACT_PRIVATE tag is set to YES all private members of a class +# will be included in the documentation. + +EXTRACT_PRIVATE = YES + +# If the EXTRACT_PACKAGE tag is set to YES all members with package or internal +# scope will be included in the documentation. + +EXTRACT_PACKAGE = NO + +# If the EXTRACT_STATIC tag is set to YES all static members of a file +# will be included in the documentation. + +EXTRACT_STATIC = YES + +# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) +# defined locally in source files will be included in the documentation. +# If set to NO only classes defined in header files are included. + +EXTRACT_LOCAL_CLASSES = YES + +# This flag is only useful for Objective-C code. When set to YES local +# methods, which are defined in the implementation section but not in +# the interface are included in the documentation. +# If set to NO (the default) only methods in the interface are included. + +EXTRACT_LOCAL_METHODS = NO + +# If this flag is set to YES, the members of anonymous namespaces will be +# extracted and appear in the documentation as a namespace called +# 'anonymous_namespace{file}', where file will be replaced with the base +# name of the file that contains the anonymous namespace. By default +# anonymous namespaces are hidden. + +EXTRACT_ANON_NSPACES = NO + +# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all +# undocumented members of documented classes, files or namespaces. +# If set to NO (the default) these members will be included in the +# various overviews, but no documentation section is generated. +# This option has no effect if EXTRACT_ALL is enabled. + +HIDE_UNDOC_MEMBERS = NO + +# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all +# undocumented classes that are normally visible in the class hierarchy. +# If set to NO (the default) these classes will be included in the various +# overviews. This option has no effect if EXTRACT_ALL is enabled. + +HIDE_UNDOC_CLASSES = NO + +# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all +# friend (class|struct|union) declarations. +# If set to NO (the default) these declarations will be included in the +# documentation. + +HIDE_FRIEND_COMPOUNDS = NO + +# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any +# documentation blocks found inside the body of a function. +# If set to NO (the default) these blocks will be appended to the +# function's detailed documentation block. + +HIDE_IN_BODY_DOCS = NO + +# The INTERNAL_DOCS tag determines if documentation +# that is typed after a \internal command is included. If the tag is set +# to NO (the default) then the documentation will be excluded. +# Set it to YES to include the internal documentation. + +INTERNAL_DOCS = NO + +# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate +# file names in lower-case letters. If set to YES upper-case letters are also +# allowed. This is useful if you have classes or files whose names only differ +# in case and if your file system supports case sensitive file names. Windows +# and Mac users are advised to set this option to NO. + +CASE_SENSE_NAMES = YES + +# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen +# will show members with their full class and namespace scopes in the +# documentation. If set to YES the scope will be hidden. + +HIDE_SCOPE_NAMES = NO + +# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen +# will put a list of the files that are included by a file in the documentation +# of that file. + +SHOW_INCLUDE_FILES = YES + +# If the FORCE_LOCAL_INCLUDES tag is set to YES then Doxygen +# will list include files with double quotes in the documentation +# rather than with sharp brackets. + +FORCE_LOCAL_INCLUDES = NO + +# If the INLINE_INFO tag is set to YES (the default) then a tag [inline] +# is inserted in the documentation for inline members. + +INLINE_INFO = YES + +# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen +# will sort the (detailed) documentation of file and class members +# alphabetically by member name. If set to NO the members will appear in +# declaration order. + +SORT_MEMBER_DOCS = YES + +# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the +# brief documentation of file, namespace and class members alphabetically +# by member name. If set to NO (the default) the members will appear in +# declaration order. + +SORT_BRIEF_DOCS = NO + +# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen +# will sort the (brief and detailed) documentation of class members so that +# constructors and destructors are listed first. If set to NO (the default) +# the constructors will appear in the respective orders defined by +# SORT_MEMBER_DOCS and SORT_BRIEF_DOCS. +# This tag will be ignored for brief docs if SORT_BRIEF_DOCS is set to NO +# and ignored for detailed docs if SORT_MEMBER_DOCS is set to NO. + +SORT_MEMBERS_CTORS_1ST = NO + +# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the +# hierarchy of group names into alphabetical order. If set to NO (the default) +# the group names will appear in their defined order. + +SORT_GROUP_NAMES = NO + +# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be +# sorted by fully-qualified names, including namespaces. If set to +# NO (the default), the class list will be sorted only by class name, +# not including the namespace part. +# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. +# Note: This option applies only to the class list, not to the +# alphabetical list. + +SORT_BY_SCOPE_NAME = NO + +# If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to +# do proper type resolution of all parameters of a function it will reject a +# match between the prototype and the implementation of a member function even +# if there is only one candidate or it is obvious which candidate to choose +# by doing a simple string match. By disabling STRICT_PROTO_MATCHING doxygen +# will still accept a match between prototype and implementation in such cases. + +STRICT_PROTO_MATCHING = NO + +# The GENERATE_TODOLIST tag can be used to enable (YES) or +# disable (NO) the todo list. This list is created by putting \todo +# commands in the documentation. + +GENERATE_TODOLIST = YES + +# The GENERATE_TESTLIST tag can be used to enable (YES) or +# disable (NO) the test list. This list is created by putting \test +# commands in the documentation. + +GENERATE_TESTLIST = YES + +# The GENERATE_BUGLIST tag can be used to enable (YES) or +# disable (NO) the bug list. This list is created by putting \bug +# commands in the documentation. + +GENERATE_BUGLIST = YES + +# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or +# disable (NO) the deprecated list. This list is created by putting +# \deprecated commands in the documentation. + +GENERATE_DEPRECATEDLIST= YES + +# The ENABLED_SECTIONS tag can be used to enable conditional +# documentation sections, marked by \if sectionname ... \endif. + +ENABLED_SECTIONS = + +# The MAX_INITIALIZER_LINES tag determines the maximum number of lines +# the initial value of a variable or macro consists of for it to appear in +# the documentation. If the initializer consists of more lines than specified +# here it will be hidden. Use a value of 0 to hide initializers completely. +# The appearance of the initializer of individual variables and macros in the +# documentation can be controlled using \showinitializer or \hideinitializer +# command in the documentation regardless of this setting. + +MAX_INITIALIZER_LINES = 30 + +# Set the SHOW_USED_FILES tag to NO to disable the list of files generated +# at the bottom of the documentation of classes and structs. If set to YES the +# list will mention the files that were used to generate the documentation. + +SHOW_USED_FILES = YES + +# Set the SHOW_FILES tag to NO to disable the generation of the Files page. +# This will remove the Files entry from the Quick Index and from the +# Folder Tree View (if specified). The default is YES. + +SHOW_FILES = YES + +# Set the SHOW_NAMESPACES tag to NO to disable the generation of the +# Namespaces page. +# This will remove the Namespaces entry from the Quick Index +# and from the Folder Tree View (if specified). The default is YES. + +SHOW_NAMESPACES = YES + +# The FILE_VERSION_FILTER tag can be used to specify a program or script that +# doxygen should invoke to get the current version for each file (typically from +# the version control system). Doxygen will invoke the program by executing (via +# popen()) the command <command> <input-file>, where <command> is the value of +# the FILE_VERSION_FILTER tag, and <input-file> is the name of an input file +# provided by doxygen. Whatever the program writes to standard output +# is used as the file version. See the manual for examples. + +FILE_VERSION_FILTER = + +# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed +# by doxygen. The layout file controls the global structure of the generated +# output files in an output format independent way. To create the layout file +# that represents doxygen's defaults, run doxygen with the -l option. +# You can optionally specify a file name after the option, if omitted +# DoxygenLayout.xml will be used as the name of the layout file. + +LAYOUT_FILE = + +# The CITE_BIB_FILES tag can be used to specify one or more bib files +# containing the references data. This must be a list of .bib files. The +# .bib extension is automatically appended if omitted. Using this command +# requires the bibtex tool to be installed. See also +# http://en.wikipedia.org/wiki/BibTeX for more info. For LaTeX the style +# of the bibliography can be controlled using LATEX_BIB_STYLE. To use this +# feature you need bibtex and perl available in the search path. + +CITE_BIB_FILES = + +#--------------------------------------------------------------------------- +# configuration options related to warning and progress messages +#--------------------------------------------------------------------------- + +# The QUIET tag can be used to turn on/off the messages that are generated +# by doxygen. Possible values are YES and NO. If left blank NO is used. + +QUIET = NO + +# The WARNINGS tag can be used to turn on/off the warning messages that are +# generated by doxygen. Possible values are YES and NO. If left blank +# NO is used. + +WARNINGS = YES + +# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings +# for undocumented members. If EXTRACT_ALL is set to YES then this flag will +# automatically be disabled. + +WARN_IF_UNDOCUMENTED = YES + +# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for +# potential errors in the documentation, such as not documenting some +# parameters in a documented function, or documenting parameters that +# don't exist or using markup commands wrongly. + +WARN_IF_DOC_ERROR = YES + +# The WARN_NO_PARAMDOC option can be enabled to get warnings for +# functions that are documented, but have no documentation for their parameters +# or return value. If set to NO (the default) doxygen will only warn about +# wrong or incomplete parameter documentation, but not about the absence of +# documentation. + +WARN_NO_PARAMDOC = NO + +# The WARN_FORMAT tag determines the format of the warning messages that +# doxygen can produce. The string should contain the $file, $line, and $text +# tags, which will be replaced by the file and line number from which the +# warning originated and the warning text. Optionally the format may contain +# $version, which will be replaced by the version of the file (if it could +# be obtained via FILE_VERSION_FILTER) + +WARN_FORMAT = "$file:$line: $text " + +# The WARN_LOGFILE tag can be used to specify a file to which warning +# and error messages should be written. If left blank the output is written +# to stderr. + +WARN_LOGFILE = + +#--------------------------------------------------------------------------- +# configuration options related to the input files +#--------------------------------------------------------------------------- + +# The INPUT tag can be used to specify the files and/or directories that contain +# documented source files. You may enter file names like "myfile.cpp" or +# directories like "/usr/src/myproject". Separate the files or directories +# with spaces. + +INPUT = coding-style-policy.md \ + stable-release-policy.md \ + road-map.md \ + compiling.md + +# This tag can be used to specify the character encoding of the source files +# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is +# also the default input encoding. Doxygen uses libiconv (or the iconv built +# into libc) for the transcoding. See http://www.gnu.org/software/libiconv for +# the list of possible encodings. + +INPUT_ENCODING = UTF-8 + +# If the value of the INPUT tag contains directories, you can use the +# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp +# and *.h) to filter out the source-files in the directories. If left +# blank the following patterns are tested: +# *.c *.cc *.cxx *.cpp *.c++ *.d *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh +# *.hxx *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.dox *.py +# *.f90 *.f *.for *.vhd *.vhdl + +FILE_PATTERNS = + +# The RECURSIVE tag can be used to turn specify whether or not subdirectories +# should be searched for input files as well. Possible values are YES and NO. +# If left blank NO is used. + +RECURSIVE = YES + +# The EXCLUDE tag can be used to specify files and/or directories that should be +# excluded from the INPUT source files. This way you can easily exclude a +# subdirectory from a directory tree whose root is specified with the INPUT tag. +# Note that relative paths are relative to the directory from which doxygen is +# run. + +EXCLUDE = + + +# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or +# directories that are symbolic links (a Unix file system feature) are excluded +# from the input. + +EXCLUDE_SYMLINKS = NO + +# If the value of the INPUT tag contains directories, you can use the +# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude +# certain files from those directories. Note that the wildcards are matched +# against the file with absolute path, so to exclude all test directories +# for example use the pattern */test/* + +EXCLUDE_PATTERNS = + +# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names +# (namespaces, classes, functions, etc.) that should be excluded from the +# output. The symbol name can be a fully qualified name, a word, or if the +# wildcard * is used, a substring. Examples: ANamespace, AClass, +# AClass::ANamespace, ANamespace::*Test + +EXCLUDE_SYMBOLS = + +# The EXAMPLE_PATH tag can be used to specify one or more files or +# directories that contain example code fragments that are included (see +# the \include command). + +EXAMPLE_PATH = + +# If the value of the EXAMPLE_PATH tag contains directories, you can use the +# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp +# and *.h) to filter out the source-files in the directories. If left +# blank all files are included. + +EXAMPLE_PATTERNS = + +# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be +# searched for input files to be used with the \include or \dontinclude +# commands irrespective of the value of the RECURSIVE tag. +# Possible values are YES and NO. If left blank NO is used. + +EXAMPLE_RECURSIVE = NO + +# The IMAGE_PATH tag can be used to specify one or more files or +# directories that contain image that are included in the documentation (see +# the \image command). + +IMAGE_PATH = + +# The INPUT_FILTER tag can be used to specify a program that doxygen should +# invoke to filter for each input file. Doxygen will invoke the filter program +# by executing (via popen()) the command <filter> <input-file>, where <filter> +# is the value of the INPUT_FILTER tag, and <input-file> is the name of an +# input file. Doxygen will then use the output that the filter program writes +# to standard output. +# If FILTER_PATTERNS is specified, this tag will be +# ignored. + +INPUT_FILTER = + +# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern +# basis. +# Doxygen will compare the file name with each pattern and apply the +# filter if there is a match. +# The filters are a list of the form: +# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further +# info on how filters are used. If FILTER_PATTERNS is empty or if +# non of the patterns match the file name, INPUT_FILTER is applied. + +FILTER_PATTERNS = + +# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using +# INPUT_FILTER) will be used to filter the input files when producing source +# files to browse (i.e. when SOURCE_BROWSER is set to YES). + +FILTER_SOURCE_FILES = NO + +# The FILTER_SOURCE_PATTERNS tag can be used to specify source filters per file +# pattern. A pattern will override the setting for FILTER_PATTERN (if any) +# and it is also possible to disable source filtering for a specific pattern +# using *.ext= (so without naming a filter). This option only has effect when +# FILTER_SOURCE_FILES is enabled. + +FILTER_SOURCE_PATTERNS = + +#--------------------------------------------------------------------------- +# configuration options related to source browsing +#--------------------------------------------------------------------------- + +# If the SOURCE_BROWSER tag is set to YES then a list of source files will +# be generated. Documented entities will be cross-referenced with these sources. +# Note: To get rid of all source code in the generated output, make sure also +# VERBATIM_HEADERS is set to NO. + +SOURCE_BROWSER = YES + +# Setting the INLINE_SOURCES tag to YES will include the body +# of functions and classes directly in the documentation. + +INLINE_SOURCES = YES + +# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct +# doxygen to hide any special comment blocks from generated source code +# fragments. Normal C, C++ and Fortran comments will always remain visible. + +STRIP_CODE_COMMENTS = YES + +# If the REFERENCED_BY_RELATION tag is set to YES +# then for each documented function all documented +# functions referencing it will be listed. + +REFERENCED_BY_RELATION = YES + +# If the REFERENCES_RELATION tag is set to YES +# then for each documented function all documented entities +# called/used by that function will be listed. + +REFERENCES_RELATION = YES + +# If the REFERENCES_LINK_SOURCE tag is set to YES (the default) +# and SOURCE_BROWSER tag is set to YES, then the hyperlinks from +# functions in REFERENCES_RELATION and REFERENCED_BY_RELATION lists will +# link to the source code. +# Otherwise they will link to the documentation. + +REFERENCES_LINK_SOURCE = YES + +# If the USE_HTAGS tag is set to YES then the references to source code +# will point to the HTML generated by the htags(1) tool instead of doxygen +# built-in source browser. The htags tool is part of GNU's global source +# tagging system (see http://www.gnu.org/software/global/global.html). You +# will need version 4.8.6 or higher. + +USE_HTAGS = NO + +# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen +# will generate a verbatim copy of the header file for each class for +# which an include is specified. Set to NO to disable this. + +VERBATIM_HEADERS = YES + +#--------------------------------------------------------------------------- +# configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- + +# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index +# of all compounds will be generated. Enable this if the project +# contains a lot of classes, structs, unions or interfaces. + +ALPHABETICAL_INDEX = YES + +# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then +# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns +# in which this list will be split (can be a number in the range [1..20]) + +COLS_IN_ALPHA_INDEX = 5 + +# In case all classes in a project start with a common prefix, all +# classes will be put under the same header in the alphabetical index. +# The IGNORE_PREFIX tag can be used to specify one or more prefixes that +# should be ignored while generating the index headers. + +IGNORE_PREFIX = + +#--------------------------------------------------------------------------- +# configuration options related to the HTML output +#--------------------------------------------------------------------------- + +# If the GENERATE_HTML tag is set to YES (the default) Doxygen will +# generate HTML output. + +GENERATE_HTML = YES + +# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `html' will be used as the default path. + +HTML_OUTPUT = html + +# The HTML_FILE_EXTENSION tag can be used to specify the file extension for +# each generated HTML page (for example: .htm,.php,.asp). If it is left blank +# doxygen will generate files with .html extension. + +HTML_FILE_EXTENSION = .html + +# The HTML_HEADER tag can be used to specify a personal HTML header for +# each generated HTML page. If it is left blank doxygen will generate a +# standard header. Note that when using a custom header you are responsible +# for the proper inclusion of any scripts and style sheets that doxygen +# needs, which is dependent on the configuration options used. +# It is advised to generate a default header using "doxygen -w html +# header.html footer.html stylesheet.css YourConfigFile" and then modify +# that header. Note that the header is subject to change so you typically +# have to redo this when upgrading to a newer version of doxygen or when +# changing the value of configuration settings such as GENERATE_TREEVIEW! + +HTML_HEADER = + +# The HTML_FOOTER tag can be used to specify a personal HTML footer for +# each generated HTML page. If it is left blank doxygen will generate a +# standard footer. + +HTML_FOOTER = + +# The HTML_STYLESHEET tag can be used to specify a user-defined cascading +# style sheet that is used by each HTML page. It can be used to +# fine-tune the look of the HTML output. If left blank doxygen will +# generate a default style sheet. Note that it is recommended to use +# HTML_EXTRA_STYLESHEET instead of this one, as it is more robust and this +# tag will in the future become obsolete. + +HTML_STYLESHEET = + +# The HTML_EXTRA_STYLESHEET tag can be used to specify an additional +# user-defined cascading style sheet that is included after the standard +# style sheets created by doxygen. Using this option one can overrule +# certain style aspects. This is preferred over using HTML_STYLESHEET +# since it does not replace the standard style sheet and is therefor more +# robust against future updates. Doxygen will copy the style sheet file to +# the output directory. + +HTML_EXTRA_STYLESHEET = + +# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or +# other source files which should be copied to the HTML output directory. Note +# that these files will be copied to the base HTML output directory. Use the +# $relpath$ marker in the HTML_HEADER and/or HTML_FOOTER files to load these +# files. In the HTML_STYLESHEET file, use the file name only. Also note that +# the files will be copied as-is; there are no commands or markers available. + +HTML_EXTRA_FILES = + +# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. +# Doxygen will adjust the colors in the style sheet and background images +# according to this color. Hue is specified as an angle on a colorwheel, +# see http://en.wikipedia.org/wiki/Hue for more information. +# For instance the value 0 represents red, 60 is yellow, 120 is green, +# 180 is cyan, 240 is blue, 300 purple, and 360 is red again. +# The allowed range is 0 to 359. + +HTML_COLORSTYLE_HUE = 220 + +# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of +# the colors in the HTML output. For a value of 0 the output will use +# grayscales only. A value of 255 will produce the most vivid colors. + +HTML_COLORSTYLE_SAT = 100 + +# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to +# the luminance component of the colors in the HTML output. Values below +# 100 gradually make the output lighter, whereas values above 100 make +# the output darker. The value divided by 100 is the actual gamma applied, +# so 80 represents a gamma of 0.8, The value 220 represents a gamma of 2.2, +# and 100 does not change the gamma. + +HTML_COLORSTYLE_GAMMA = 80 + +# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML +# page will contain the date and time when the page was generated. Setting +# this to NO can help when comparing the output of multiple runs. + +HTML_TIMESTAMP = YES + +# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML +# documentation will contain sections that can be hidden and shown after the +# page has loaded. + +HTML_DYNAMIC_SECTIONS = NO + +# With HTML_INDEX_NUM_ENTRIES one can control the preferred number of +# entries shown in the various tree structured indices initially; the user +# can expand and collapse entries dynamically later on. Doxygen will expand +# the tree to such a level that at most the specified number of entries are +# visible (unless a fully collapsed tree already exceeds this amount). +# So setting the number of entries 1 will produce a full collapsed tree by +# default. 0 is a special value representing an infinite number of entries +# and will result in a full expanded tree by default. + +HTML_INDEX_NUM_ENTRIES = 100 + +# If the GENERATE_DOCSET tag is set to YES, additional index files +# will be generated that can be used as input for Apple's Xcode 3 +# integrated development environment, introduced with OSX 10.5 (Leopard). +# To create a documentation set, doxygen will generate a Makefile in the +# HTML output directory. Running make will produce the docset in that +# directory and running "make install" will install the docset in +# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find +# it at startup. +# See http://developer.apple.com/tools/creatingdocsetswithdoxygen.html +# for more information. + +GENERATE_DOCSET = NO + +# When GENERATE_DOCSET tag is set to YES, this tag determines the name of the +# feed. A documentation feed provides an umbrella under which multiple +# documentation sets from a single provider (such as a company or product suite) +# can be grouped. + +DOCSET_FEEDNAME = "Doxygen generated docs" + +# When GENERATE_DOCSET tag is set to YES, this tag specifies a string that +# should uniquely identify the documentation set bundle. This should be a +# reverse domain-name style string, e.g. com.mycompany.MyDocSet. Doxygen +# will append .docset to the name. + +DOCSET_BUNDLE_ID = org.doxygen.Project + +# When GENERATE_PUBLISHER_ID tag specifies a string that should uniquely +# identify the documentation publisher. This should be a reverse domain-name +# style string, e.g. com.mycompany.MyDocSet.documentation. + +DOCSET_PUBLISHER_ID = org.doxygen.Publisher + +# The GENERATE_PUBLISHER_NAME tag identifies the documentation publisher. + +DOCSET_PUBLISHER_NAME = Publisher + +# If the GENERATE_HTMLHELP tag is set to YES, additional index files +# will be generated that can be used as input for tools like the +# Microsoft HTML help workshop to generate a compiled HTML help file (.chm) +# of the generated HTML documentation. + +GENERATE_HTMLHELP = NO + +# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can +# be used to specify the file name of the resulting .chm file. You +# can add a path in front of the file if the result should not be +# written to the html output directory. + +CHM_FILE = + +# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can +# be used to specify the location (absolute path including file name) of +# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run +# the HTML help compiler on the generated index.hhp. + +HHC_LOCATION = + +# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag +# controls if a separate .chi index file is generated (YES) or that +# it should be included in the master .chm file (NO). + +GENERATE_CHI = NO + +# If the GENERATE_HTMLHELP tag is set to YES, the CHM_INDEX_ENCODING +# is used to encode HtmlHelp index (hhk), content (hhc) and project file +# content. + +CHM_INDEX_ENCODING = + +# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag +# controls whether a binary table of contents is generated (YES) or a +# normal table of contents (NO) in the .chm file. + +BINARY_TOC = NO + +# The TOC_EXPAND flag can be set to YES to add extra items for group members +# to the contents of the HTML help documentation and to the tree view. + +TOC_EXPAND = NO + +# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and +# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated +# that can be used as input for Qt's qhelpgenerator to generate a +# Qt Compressed Help (.qch) of the generated HTML documentation. + +GENERATE_QHP = NO + +# If the QHG_LOCATION tag is specified, the QCH_FILE tag can +# be used to specify the file name of the resulting .qch file. +# The path specified is relative to the HTML output folder. + +QCH_FILE = + +# The QHP_NAMESPACE tag specifies the namespace to use when generating +# Qt Help Project output. For more information please see +# http://doc.trolltech.com/qthelpproject.html#namespace + +QHP_NAMESPACE = org.doxygen.Project + +# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating +# Qt Help Project output. For more information please see +# http://doc.trolltech.com/qthelpproject.html#virtual-folders + +QHP_VIRTUAL_FOLDER = doc + +# If QHP_CUST_FILTER_NAME is set, it specifies the name of a custom filter to +# add. For more information please see +# http://doc.trolltech.com/qthelpproject.html#custom-filters + +QHP_CUST_FILTER_NAME = + +# The QHP_CUST_FILT_ATTRS tag specifies the list of the attributes of the +# custom filter to add. For more information please see +# <a href="http://doc.trolltech.com/qthelpproject.html#custom-filters"> +# Qt Help Project / Custom Filters</a>. + +QHP_CUST_FILTER_ATTRS = + +# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this +# project's +# filter section matches. +# <a href="http://doc.trolltech.com/qthelpproject.html#filter-attributes"> +# Qt Help Project / Filter Attributes</a>. + +QHP_SECT_FILTER_ATTRS = + +# If the GENERATE_QHP tag is set to YES, the QHG_LOCATION tag can +# be used to specify the location of Qt's qhelpgenerator. +# If non-empty doxygen will try to run qhelpgenerator on the generated +# .qhp file. + +QHG_LOCATION = + +# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files +# will be generated, which together with the HTML files, form an Eclipse help +# plugin. To install this plugin and make it available under the help contents +# menu in Eclipse, the contents of the directory containing the HTML and XML +# files needs to be copied into the plugins directory of eclipse. The name of +# the directory within the plugins directory should be the same as +# the ECLIPSE_DOC_ID value. After copying Eclipse needs to be restarted before +# the help appears. + +GENERATE_ECLIPSEHELP = NO + +# A unique identifier for the eclipse help plugin. When installing the plugin +# the directory name containing the HTML and XML files should also have +# this name. + +ECLIPSE_DOC_ID = org.doxygen.Project + +# The DISABLE_INDEX tag can be used to turn on/off the condensed index (tabs) +# at top of each HTML page. The value NO (the default) enables the index and +# the value YES disables it. Since the tabs have the same information as the +# navigation tree you can set this option to NO if you already set +# GENERATE_TREEVIEW to YES. + +DISABLE_INDEX = NO + +# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index +# structure should be generated to display hierarchical information. +# If the tag value is set to YES, a side panel will be generated +# containing a tree-like index structure (just like the one that +# is generated for HTML Help). For this to work a browser that supports +# JavaScript, DHTML, CSS and frames is required (i.e. any modern browser). +# Windows users are probably better off using the HTML help feature. +# Since the tree basically has the same information as the tab index you +# could consider to set DISABLE_INDEX to NO when enabling this option. + +GENERATE_TREEVIEW = YES + +# The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values +# (range [0,1..20]) that doxygen will group on one line in the generated HTML +# documentation. Note that a value of 0 will completely suppress the enum +# values from appearing in the overview section. + +ENUM_VALUES_PER_LINE = 4 + +# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be +# used to set the initial width (in pixels) of the frame in which the tree +# is shown. + +TREEVIEW_WIDTH = 250 + +# When the EXT_LINKS_IN_WINDOW option is set to YES doxygen will open +# links to external symbols imported via tag files in a separate window. + +EXT_LINKS_IN_WINDOW = NO + +# Use this tag to change the font size of Latex formulas included +# as images in the HTML documentation. The default is 10. Note that +# when you change the font size after a successful doxygen run you need +# to manually remove any form_*.png images from the HTML output directory +# to force them to be regenerated. + +FORMULA_FONTSIZE = 10 + +# Use the FORMULA_TRANPARENT tag to determine whether or not the images +# generated for formulas are transparent PNGs. Transparent PNGs are +# not supported properly for IE 6.0, but are supported on all modern browsers. +# Note that when changing this option you need to delete any form_*.png files +# in the HTML output before the changes have effect. + +FORMULA_TRANSPARENT = YES + +# Enable the USE_MATHJAX option to render LaTeX formulas using MathJax +# (see http://www.mathjax.org) which uses client side Javascript for the +# rendering instead of using prerendered bitmaps. Use this if you do not +# have LaTeX installed or if you want to formulas look prettier in the HTML +# output. When enabled you may also need to install MathJax separately and +# configure the path to it using the MATHJAX_RELPATH option. + +USE_MATHJAX = NO + +# When MathJax is enabled you need to specify the location relative to the +# HTML output directory using the MATHJAX_RELPATH option. The destination +# directory should contain the MathJax.js script. For instance, if the mathjax +# directory is located at the same level as the HTML output directory, then +# MATHJAX_RELPATH should be ../mathjax. The default value points to +# the MathJax Content Delivery Network so you can quickly see the result without +# installing MathJax. +# However, it is strongly recommended to install a local +# copy of MathJax from http://www.mathjax.org before deployment. + +MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest + +# The MATHJAX_EXTENSIONS tag can be used to specify one or MathJax extension +# names that should be enabled during MathJax rendering. + +MATHJAX_EXTENSIONS = + +# When the SEARCHENGINE tag is enabled doxygen will generate a search box +# for the HTML output. The underlying search engine uses javascript +# and DHTML and should work on any modern browser. Note that when using +# HTML help (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets +# (GENERATE_DOCSET) there is already a search function so this one should +# typically be disabled. For large projects the javascript based search engine +# can be slow, then enabling SERVER_BASED_SEARCH may provide a better solution. + +SEARCHENGINE = NO + +# When the SERVER_BASED_SEARCH tag is enabled the search engine will be +# implemented using a PHP enabled web server instead of at the web client +# using Javascript. Doxygen will generate the search PHP script and index +# file to put on the web server. The advantage of the server +# based approach is that it scales better to large projects and allows +# full text search. The disadvantages are that it is more difficult to setup +# and does not have live searching capabilities. + +SERVER_BASED_SEARCH = NO + +#--------------------------------------------------------------------------- +# configuration options related to the LaTeX output +#--------------------------------------------------------------------------- + +# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will +# generate Latex output. + +GENERATE_LATEX = NO + +# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `latex' will be used as the default path. + +LATEX_OUTPUT = latex + +# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be +# invoked. If left blank `latex' will be used as the default command name. +# Note that when enabling USE_PDFLATEX this option is only used for +# generating bitmaps for formulas in the HTML output, but not in the +# Makefile that is written to the output directory. + +LATEX_CMD_NAME = latex + +# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to +# generate index for LaTeX. If left blank `makeindex' will be used as the +# default command name. + +MAKEINDEX_CMD_NAME = makeindex + +# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact +# LaTeX documents. This may be useful for small projects and may help to +# save some trees in general. + +COMPACT_LATEX = NO + +# The PAPER_TYPE tag can be used to set the paper type that is used +# by the printer. Possible values are: a4, letter, legal and +# executive. If left blank a4wide will be used. + +PAPER_TYPE = a4wide + +# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX +# packages that should be included in the LaTeX output. + +EXTRA_PACKAGES = + +# The LATEX_HEADER tag can be used to specify a personal LaTeX header for +# the generated latex document. The header should contain everything until +# the first chapter. If it is left blank doxygen will generate a +# standard header. Notice: only use this tag if you know what you are doing! + +LATEX_HEADER = + +# The LATEX_FOOTER tag can be used to specify a personal LaTeX footer for +# the generated latex document. The footer should contain everything after +# the last chapter. If it is left blank doxygen will generate a +# standard footer. Notice: only use this tag if you know what you are doing! + +LATEX_FOOTER = + +# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated +# is prepared for conversion to pdf (using ps2pdf). The pdf file will +# contain links (just like the HTML output) instead of page references +# This makes the output suitable for online browsing using a pdf viewer. + +PDF_HYPERLINKS = NO + +# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of +# plain latex in the generated Makefile. Set this option to YES to get a +# higher quality PDF documentation. + +USE_PDFLATEX = NO + +# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. +# command to the generated LaTeX files. This will instruct LaTeX to keep +# running if errors occur, instead of asking the user for help. +# This option is also used when generating formulas in HTML. + +LATEX_BATCHMODE = NO + +# If LATEX_HIDE_INDICES is set to YES then doxygen will not +# include the index chapters (such as File Index, Compound Index, etc.) +# in the output. + +LATEX_HIDE_INDICES = NO + +# If LATEX_SOURCE_CODE is set to YES then doxygen will include +# source code with syntax highlighting in the LaTeX output. +# Note that which sources are shown also depends on other settings +# such as SOURCE_BROWSER. + +LATEX_SOURCE_CODE = NO + +# The LATEX_BIB_STYLE tag can be used to specify the style to use for the +# bibliography, e.g. plainnat, or ieeetr. The default style is "plain". See +# http://en.wikipedia.org/wiki/BibTeX for more info. + +LATEX_BIB_STYLE = plain + +#--------------------------------------------------------------------------- +# configuration options related to the RTF output +#--------------------------------------------------------------------------- + +# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output +# The RTF output is optimized for Word 97 and may not look very pretty with +# other RTF readers or editors. + +GENERATE_RTF = NO + +# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `rtf' will be used as the default path. + +RTF_OUTPUT = rtf + +# If the COMPACT_RTF tag is set to YES Doxygen generates more compact +# RTF documents. This may be useful for small projects and may help to +# save some trees in general. + +COMPACT_RTF = NO + +# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated +# will contain hyperlink fields. The RTF file will +# contain links (just like the HTML output) instead of page references. +# This makes the output suitable for online browsing using WORD or other +# programs which support those fields. +# Note: wordpad (write) and others do not support links. + +RTF_HYPERLINKS = NO + +# Load style sheet definitions from file. Syntax is similar to doxygen's +# config file, i.e. a series of assignments. You only have to provide +# replacements, missing definitions are set to their default value. + +RTF_STYLESHEET_FILE = + +# Set optional variables used in the generation of an rtf document. +# Syntax is similar to doxygen's config file. + +RTF_EXTENSIONS_FILE = + +#--------------------------------------------------------------------------- +# configuration options related to the man page output +#--------------------------------------------------------------------------- + +# If the GENERATE_MAN tag is set to YES (the default) Doxygen will +# generate man pages + +GENERATE_MAN = NO + +# The MAN_OUTPUT tag is used to specify where the man pages will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `man' will be used as the default path. + +MAN_OUTPUT = man + +# The MAN_EXTENSION tag determines the extension that is added to +# the generated man pages (default is the subroutine's section .3) + +MAN_EXTENSION = .3 + +# If the MAN_LINKS tag is set to YES and Doxygen generates man output, +# then it will generate one additional man file for each entity +# documented in the real man page(s). These additional files +# only source the real man page, but without them the man command +# would be unable to find the correct page. The default is NO. + +MAN_LINKS = NO + +#--------------------------------------------------------------------------- +# configuration options related to the XML output +#--------------------------------------------------------------------------- + +# If the GENERATE_XML tag is set to YES Doxygen will +# generate an XML file that captures the structure of +# the code including all documentation. + +GENERATE_XML = NO + +# The XML_OUTPUT tag is used to specify where the XML pages will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `xml' will be used as the default path. + +XML_OUTPUT = xml + +XML_PROGRAMLISTING = YES + +#--------------------------------------------------------------------------- +# configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- + +# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will +# generate an AutoGen Definitions (see autogen.sf.net) file +# that captures the structure of the code including all +# documentation. Note that this feature is still experimental +# and incomplete at the moment. + +GENERATE_AUTOGEN_DEF = NO + +#--------------------------------------------------------------------------- +# configuration options related to the Perl module output +#--------------------------------------------------------------------------- + +# If the GENERATE_PERLMOD tag is set to YES Doxygen will +# generate a Perl module file that captures the structure of +# the code including all documentation. Note that this +# feature is still experimental and incomplete at the +# moment. + +GENERATE_PERLMOD = NO + +# If the PERLMOD_LATEX tag is set to YES Doxygen will generate +# the necessary Makefile rules, Perl scripts and LaTeX code to be able +# to generate PDF and DVI output from the Perl module output. + +PERLMOD_LATEX = NO + +# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be +# nicely formatted so it can be parsed by a human reader. +# This is useful +# if you want to understand what is going on. +# On the other hand, if this +# tag is set to NO the size of the Perl module output will be much smaller +# and Perl will parse it just the same. + +PERLMOD_PRETTY = YES + +# The names of the make variables in the generated doxyrules.make file +# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. +# This is useful so different doxyrules.make files included by the same +# Makefile don't overwrite each other's variables. + +PERLMOD_MAKEVAR_PREFIX = + +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- + +# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will +# evaluate all C-preprocessor directives found in the sources and include +# files. + +ENABLE_PREPROCESSING = YES + +# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro +# names in the source code. If set to NO (the default) only conditional +# compilation will be performed. Macro expansion can be done in a controlled +# way by setting EXPAND_ONLY_PREDEF to YES. + +MACRO_EXPANSION = NO + +# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES +# then the macro expansion is limited to the macros specified with the +# PREDEFINED and EXPAND_AS_DEFINED tags. + +EXPAND_ONLY_PREDEF = NO + +# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files +# pointed to by INCLUDE_PATH will be searched when a #include is found. + +SEARCH_INCLUDES = YES + +# The INCLUDE_PATH tag can be used to specify one or more directories that +# contain include files that are not input files but should be processed by +# the preprocessor. + +INCLUDE_PATH = + +# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard +# patterns (like *.h and *.hpp) to filter out the header-files in the +# directories. If left blank, the patterns specified with FILE_PATTERNS will +# be used. + +INCLUDE_FILE_PATTERNS = *.h + +# The PREDEFINED tag can be used to specify one or more macro names that +# are defined before the preprocessor is started (similar to the -D option of +# gcc). The argument of the tag is a list of macros of the form: name +# or name=definition (no spaces). If the definition and the = are +# omitted =1 is assumed. To prevent a macro definition from being +# undefined via #undef or recursively expanded use the := operator +# instead of the = operator. + +PREDEFINED = + +# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then +# this tag can be used to specify a list of macro names that should be expanded. +# The macro definition that is found in the sources will be used. +# Use the PREDEFINED tag if you want to use a different macro definition that +# overrules the definition found in the source code. + +EXPAND_AS_DEFINED = + +# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then +# doxygen's preprocessor will remove all references to function-like macros +# that are alone on a line, have an all uppercase name, and do not end with a +# semicolon, because these will confuse the parser if not removed. + +SKIP_FUNCTION_MACROS = YES + +#--------------------------------------------------------------------------- +# Configuration::additions related to external references +#--------------------------------------------------------------------------- + +# The TAGFILES option can be used to specify one or more tagfiles. For each +# tag file the location of the external documentation should be added. The +# format of a tag file without this location is as follows: +# +# TAGFILES = file1 file2 ... +# Adding location for the tag files is done as follows: +# +# TAGFILES = file1=loc1 "file2 = loc2" ... +# where "loc1" and "loc2" can be relative or absolute paths +# or URLs. Note that each tag file must have a unique name (where the name does +# NOT include the path). If a tag file is not located in the directory in which +# doxygen is run, you must also specify the path to the tagfile here. + +TAGFILES = + +# When a file name is specified after GENERATE_TAGFILE, doxygen will create +# a tag file that is based on the input files it reads. + +GENERATE_TAGFILE = + +# If the ALLEXTERNALS tag is set to YES all external classes will be listed +# in the class index. If set to NO only the inherited external classes +# will be listed. + +ALLEXTERNALS = NO + +# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed +# in the modules index. If set to NO, only the current project's groups will +# be listed. + +EXTERNAL_GROUPS = YES + +# The PERL_PATH should be the absolute path and name of the perl script +# interpreter (i.e. the result of `which perl'). + +PERL_PATH = /usr/bin/perl + +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- + +# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will +# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base +# or super classes. Setting the tag to NO turns the diagrams off. Note that +# this option also works with HAVE_DOT disabled, but it is recommended to +# install and use dot, since it yields more powerful graphs. + +CLASS_DIAGRAMS = YES + +# You can define message sequence charts within doxygen comments using the \msc +# command. Doxygen will then run the mscgen tool (see +# http://www.mcternan.me.uk/mscgen/) to produce the chart and insert it in the +# documentation. The MSCGEN_PATH tag allows you to specify the directory where +# the mscgen tool resides. If left empty the tool is assumed to be found in the +# default search path. + +MSCGEN_PATH = + +# If set to YES, the inheritance and collaboration graphs will hide +# inheritance and usage relations if the target is undocumented +# or is not a class. + +HIDE_UNDOC_RELATIONS = YES + +# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is +# available from the path. This tool is part of Graphviz, a graph visualization +# toolkit from AT&T and Lucent Bell Labs. The other options in this section +# have no effect if this option is set to NO (the default) + +HAVE_DOT = NO + +# The DOT_NUM_THREADS specifies the number of dot invocations doxygen is +# allowed to run in parallel. When set to 0 (the default) doxygen will +# base this on the number of processors available in the system. You can set it +# explicitly to a value larger than 0 to get control over the balance +# between CPU load and processing speed. + +DOT_NUM_THREADS = 0 + +# By default doxygen will use the Helvetica font for all dot files that +# doxygen generates. When you want a differently looking font you can specify +# the font name using DOT_FONTNAME. You need to make sure dot is able to find +# the font, which can be done by putting it in a standard location or by setting +# the DOTFONTPATH environment variable or by setting DOT_FONTPATH to the +# directory containing the font. + +DOT_FONTNAME = Helvetica + +# The DOT_FONTSIZE tag can be used to set the size of the font of dot graphs. +# The default size is 10pt. + +DOT_FONTSIZE = 10 + +# By default doxygen will tell dot to use the Helvetica font. +# If you specify a different font using DOT_FONTNAME you can use DOT_FONTPATH to +# set the path where dot can find it. + +DOT_FONTPATH = + +# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for each documented class showing the direct and +# indirect inheritance relations. Setting this tag to YES will force the +# CLASS_DIAGRAMS tag to NO. + +CLASS_GRAPH = YES + +# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for each documented class showing the direct and +# indirect implementation dependencies (inheritance, containment, and +# class references variables) of the class with other documented classes. + +COLLABORATION_GRAPH = YES + +# If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for groups, showing the direct groups dependencies + +GROUP_GRAPHS = YES + +# If the UML_LOOK tag is set to YES doxygen will generate inheritance and +# collaboration diagrams in a style similar to the OMG's Unified Modeling +# Language. + +UML_LOOK = NO + +# If the UML_LOOK tag is enabled, the fields and methods are shown inside +# the class node. If there are many fields or methods and many nodes the +# graph may become too big to be useful. The UML_LIMIT_NUM_FIELDS +# threshold limits the number of items for each type to make the size more +# managable. Set this to 0 for no limit. Note that the threshold may be +# exceeded by 50% before the limit is enforced. + +UML_LIMIT_NUM_FIELDS = 10 + +# If set to YES, the inheritance and collaboration graphs will show the +# relations between templates and their instances. + +TEMPLATE_RELATIONS = YES + +# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT +# tags are set to YES then doxygen will generate a graph for each documented +# file showing the direct and indirect include dependencies of the file with +# other documented files. + +INCLUDE_GRAPH = YES + +# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and +# HAVE_DOT tags are set to YES then doxygen will generate a graph for each +# documented header file showing the documented files that directly or +# indirectly include this file. + +INCLUDED_BY_GRAPH = YES + +# If the CALL_GRAPH and HAVE_DOT options are set to YES then +# doxygen will generate a call dependency graph for every global function +# or class method. Note that enabling this option will significantly increase +# the time of a run. So in most cases it will be better to enable call graphs +# for selected functions only using the \callgraph command. + +CALL_GRAPH = NO + +# If the CALLER_GRAPH and HAVE_DOT tags are set to YES then +# doxygen will generate a caller dependency graph for every global function +# or class method. Note that enabling this option will significantly increase +# the time of a run. So in most cases it will be better to enable caller +# graphs for selected functions only using the \callergraph command. + +CALLER_GRAPH = NO + +# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen +# will generate a graphical hierarchy of all classes instead of a textual one. + +GRAPHICAL_HIERARCHY = YES + +# If the DIRECTORY_GRAPH and HAVE_DOT tags are set to YES +# then doxygen will show the dependencies a directory has on other directories +# in a graphical way. The dependency relations are determined by the #include +# relations between the files in the directories. + +DIRECTORY_GRAPH = YES + +# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images +# generated by dot. Possible values are svg, png, jpg, or gif. +# If left blank png will be used. If you choose svg you need to set +# HTML_FILE_EXTENSION to xhtml in order to make the SVG files +# visible in IE 9+ (other browsers do not have this requirement). + +DOT_IMAGE_FORMAT = png + +# If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to +# enable generation of interactive SVG images that allow zooming and panning. +# Note that this requires a modern browser other than Internet Explorer. +# Tested and working are Firefox, Chrome, Safari, and Opera. For IE 9+ you +# need to set HTML_FILE_EXTENSION to xhtml in order to make the SVG files +# visible. Older versions of IE do not have SVG support. + +INTERACTIVE_SVG = NO + +# The tag DOT_PATH can be used to specify the path where the dot tool can be +# found. If left blank, it is assumed the dot tool can be found in the path. + +DOT_PATH = + +# The DOTFILE_DIRS tag can be used to specify one or more directories that +# contain dot files that are included in the documentation (see the +# \dotfile command). + +DOTFILE_DIRS = + +# The MSCFILE_DIRS tag can be used to specify one or more directories that +# contain msc files that are included in the documentation (see the +# \mscfile command). + +MSCFILE_DIRS = + +# The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of +# nodes that will be shown in the graph. If the number of nodes in a graph +# becomes larger than this value, doxygen will truncate the graph, which is +# visualized by representing a node as a red box. Note that doxygen if the +# number of direct children of the root node in a graph is already larger than +# DOT_GRAPH_MAX_NODES then the graph will not be shown at all. Also note +# that the size of a graph can be further restricted by MAX_DOT_GRAPH_DEPTH. + +DOT_GRAPH_MAX_NODES = 50 + +# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the +# graphs generated by dot. A depth value of 3 means that only nodes reachable +# from the root by following a path via at most 3 edges will be shown. Nodes +# that lay further from the root node will be omitted. Note that setting this +# option to 1 or 2 may greatly reduce the computation time needed for large +# code bases. Also note that the size of a graph can be further restricted by +# DOT_GRAPH_MAX_NODES. Using a depth of 0 means no depth restriction. + +MAX_DOT_GRAPH_DEPTH = 0 + +# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent +# background. This is disabled by default, because dot on Windows does not +# seem to support this out of the box. Warning: Depending on the platform used, +# enabling this option may lead to badly anti-aliased labels on the edges of +# a graph (i.e. they become hard to read). + +DOT_TRANSPARENT = NO + +# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output +# files in one run (i.e. multiple -o and -T options on the command line). This +# makes dot run faster, but since only newer versions of dot (>1.8.10) +# support this, this feature is disabled by default. + +DOT_MULTI_TARGETS = NO + +# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will +# generate a legend page explaining the meaning of the various boxes and +# arrows in the dot generated graphs. + +GENERATE_LEGEND = YES + +# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will +# remove the intermediate dot files that are used to generate +# the various graphs. + +DOT_CLEANUP = YES diff --git a/Documentation/development/coding-style-policy.md b/Documentation/development/coding-style-policy.md new file mode 100644 index 0000000..2a54dc1 --- /dev/null +++ b/Documentation/development/coding-style-policy.md @@ -0,0 +1,800 @@ +# KiCad C++ Source Code Style Guide # + +Latest Publishing: February 2013 + +First Published: September 2010 + +written by + +Wayne Stambaugh \<<stambaughw@verizon.net>\> +and +Dick Hollenbeck \<<dick@softplc.com>\> + +[TOC] + +# 1. Introduction # {#intro} +The purpose of this document is to provide a reference guide for KiCad +developers about how source code should be styled and formatted in +KiCad. It is not a comprehensive programming guide because it does not +discuss many things such as software engineering strategies, source +directories, existing classes, or how to internationalize text. The goal +is to make all of the KiCad source conform to this guide. + +## 1.1 Why Coding Style Matters ## {#why} +You may be thinking to yourself that using the style defined in this +document will not make you a good programmer and you would be correct. +Any given coding style is no substitute for experience. However, any +experienced coder will tell that the only thing worse than looking at +code that is not in your preferred coding style, is looking at twenty +different coding styles that are not your preferred coding style. +Consistency makes a) problems easier to spot, and b) looking at code for +long periods of time more tolerable. + +## 1.2 Enforcement ## {#enforcement} +The KiCad coding police are not going to break down your door and beat +you with your keyboard if you don't follow these guidelines (although +there are those who would argue that they should). However, there are +some very sound reasons why you should follow them. If you are +contributing patches, you are much more likely to be taken seriously by +the primary developers if your patches are formatted correctly. Busy +developers don't have the time to go back and reformat your code. If you +have a desire to become a regular KiCad developer with commit access to +the development branch, you're not likely to get a glowing +recommendation by the lead developers if you will not follow these +guidelines. It is just good programming courtesy to follow this policy +because it is respectful of the investment already made by the existing +developers. The other KiCad developers will appreciate your effort. + +**Warning** + +**Do not modify this document without the consent of the project +leader. All changes to this document require approval.** + + +# 2. Naming Conventions # {#naming_conventions} +Before delving into anything as esoteric as indentation and formatting, +naming conventions need to be addressed. This section does not attempt +to define what names you use for your code. Rather, it defines the style +for naming. See the references section for links to some excellent +coding references. When defining multiple word names use the following +conventions for improved readability: + +- Use underscores for all upper and all lower case variables to make + multiple word names more readable. +- Use camel case for mixed case variable names. + +Avoid mixing camel case and underscores. + +**Examples** +~~~~~~~~~~~~~{.cpp} + CamelCaseName // if camelcase, then no underscores + all_lower_case_name + ALL_UPPER_CASE_NAME +~~~~~~~~~~~~~ + +## 2.1 Class, Type Definitions, Name Space, and Macro Names ## {#definitions} +Class, typedef, enum, name space, and macro names should be comprised of +all capital letters. + +**Examples** +~~~~~~~~~~~~~{.cpp} + class SIMPLE + #define LONG_MACRO_WITH_UNDERSCORES + typedef boost::ptr_vector<PIN> PIN_LIST; + enum KICAD_T {...}; +~~~~~~~~~~~~~ + +## 2.2 Local, Private and Automatic Variables ## {#local_variables} +The first character of automatic, static local, and private variable +names should be lower case. This indicates that the variable will not be +“visible” outside of the function, file, or class where they are +defined, respectively. The limited visibility is being acknowledged with +the lowercase starting letter, where lowercase is considered to be less +boisterous than uppercase. + +**Examples** +~~~~~~~~~~~~~{.cpp} + int i; + double aPrivateVariable; + static char* static_variable = NULL; +~~~~~~~~~~~~~ + +## 2.3 Public and Global Variables ## {#global_variables} +The first character of public and global variable names are to be +uppercase. This indicates that the variable is visible outside the class +or file in which it was defined. (An exception is the use of prefix `g_` +which is also sometimes used to indicate a global variable.) + +**Example** +~~~~~~~~~~~~~{.cpp} + char* GlobalVariable; +~~~~~~~~~~~~~ + +## 2.4 Local, Private and Static Functions ## {#functions} +The first character of local, private, and static functions should be +lower case. This indicates that the function is not visible outside the +class or file where it is defined. + +**Example** +~~~~~~~~~~~~~{.cpp} + bool isModified(); + static int buildList( int* list ); +~~~~~~~~~~~~~ + +## 2.5 Function Arguments ## {#function_arguments} +Function arguments are prefixed with an 'a' to indicate these are +arguments to a function. The 'a' stands for “argument”, and it also +enables clever and concise Doxygen comments. + +**Example** +~~~~~~~~~~~~~{.cpp} + /*/** */* + * Function SetFoo + * takes aFoo and copies it into this instance. + */ + void SetFoo( int aFoo ); +~~~~~~~~~~~~~ + +Notice how the reader can say “a Foo” to himself when reading this. + +## 2.6 Pointers ## {#pointers} +It is not desired to identify a pointer by building a 'p' into the +variable name. The pointer aspect of the variable pertains to type, not +purpose. + +**Example** +~~~~~~~~~~~~~{.cpp} + MODULE* module; +~~~~~~~~~~~~~ + +The purpose of the variable is that it represents a MODULE. Something +like `p_module` would only make that harder to discern. + +## 2.7 Accessing Member Variables and Member Functions ## {#accessing_members} +We do not use “`this->`” to access either member variables or member +functions from within the containing class. We let C++ perform this for +us. + + +# 3. Commenting # {#commenting} +Comments in KiCad typically fall into two categories: in line code +comments and Doxygen comments. In line comments have no set formatting +rules other than they should have the same indent level as the code if +they do not follow a statement. In line comments that follow statements +should not exceed 99 columns unless absolutely necessary. The prevents +word wrapping in an editor when the viewable columns is set to 100. In +line comments can use either the C++ or the C commenting style, but C++ +comments are preferred for single line comments or comments consisting +of only a few lines. + +## 3.1 Blank Lines Above Comments ## {#blank_lines_above_comments} +If a comment is the first thing on a line, then that comment should have +one or more blank lines above them. One blank line is preferred. + +## 3.2 Doxygen ## {#doxygen} +Doxygen is a C++ source code documenting tool used by the project. Descriptive +*.html files can be generated from the source code by installing Doxygen and +building the target named **doxygen-docs**. + + $ cd <kicad_build_base> + $ make doxygen-docs + +The \*.html files will be placed into +\<kicad\_project\_base\>/Documentation/doxygen/html/ + +Doxygen comments are used to build developer documentation from the +source code. They should normally be only placed in header files and not +in \*.cpp files. This eliminates the obligation to keep two comments in +agreement with each other. is if the class, function, or enum, etc. is +only defined in a \*.cpp source file and not present in any header file, +in which case the Doxygen comments should go into the \*.cpp source file. +Again, avoid duplicating the Doxygen comments in both the header and +\*.cpp source files. + +KiCad uses the JAVADOC comment style defined in the [“Documenting the +code”][doccode] section of the Doxygen [manual][manual]. Don't forget +to use the special Doxygen tags: bug, todo, deprecated, etc., so other +developers can quickly get useful information about your code. It is +good practice to actually generate the Doxygen \*.html files by +building target doxygen-docs, and then to review the quality of your +Doxygen comments with a web browser before submitting a patch. + +[doccode]: http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html +[manual]: http://www.stack.nl/~dimitri/doxygen/manual.html + +### 3.2.1 Function Comments ### {#function_comments} +These go into a header file, unless the function is a private (i.e. +static) function known only to a \*.cpp file. The format of a function +comment is chosen to serve a dual purpose role: delineation of the +function declaration within the source code and to create a consistent +leading sentence in the doxygen html output. The chosen format is +“Function \<name\>” as shown in the example below. + +**Example** +~~~~~~~~~~~~~{.cpp} + /*/** */* + * Function Print + * formats and writes text to the output stream. + * @param nestLevel is the multiple of spaces to precede the output with. + * @param fmt is a printf() style format string. + * @param ... is a variable list of parameters that will get blended into + * the output under control of the format string. + * @return int - the number of characters output. + * @throw IO_ERROR, if there is a problem outputting, such asisk. + */ + int PRINTF_FUNC Print( int nestLevel, + const char* fmt, ... ) throw( IO_ERROR ); +~~~~~~~~~~~~~ + +The “Function \<name\>” text goes on the 2nd line of the comment. The +\@return keyword if present, should show the type of the return value +followed by a hiphen. The \@param keyword names a function parameter +and the text following should flow like a normal English sentence. + +### 3.2.2 Class Comments ### {#class_comments} +A class comment describes a class declaration by giving the purpose and +use of the class. Its format is similar to a function comment. Doxygen +can use the html \<p\> (paragraph designation) to begin a new paragraph +in its output. So if the text of the comment is large, break it put into +multiple paragraphs. + +**Example** +~~~~~~~~~~~~~{.cpp} + /*/** */* + * Class OUTPUTFORMATTER + * is an important interface (abstract) class used to output UTF8 text in + * a convenient way. The primary interface is "printf() - like" but + * with support for indentation control. The destination of the 8 bit + * wide text is up to the implementer. + * <p> + * The implementer only has to implement the write() function, but can + * also optionally re-implement GetQuoteChar(). + * <p> + * If you want to output a wxString, then use CONV_TO_UTF8() on it + * before passing it as an argument to Print(). + * <p> + * Since this is an abstract interface, only classes derived from + * this one may actually be used. + */ + class OUTPUTFORMATTER + { +~~~~~~~~~~~~~ + + +# 4. Formatting # {#formatting} +This section defines the formatting style used in the KiCad source. + +## 4.1 Indentation ## {#indentation} +The indentation level for the KiCad source code is defined as four +spaces. Please do not use tabs. + +### 4.1.1 Defines ### {#defines} +There should be only one space after a \#define statement. + +### 4.1.2 Column Alignment ### {#column_alignment} +Please try to align multiple consecutive similar lines into consistent +columns when possible, such as \#define lines which can be thought of as +containing 4 columns: \#define, symbol, value, and comment. Notice how +all 4 columns are aligned in the example below. + +**Example** +~~~~~~~~~~~~~{.cpp} + #define LN_RED 12 // my favorite + #define LN_GREEN 13 // eco friendly +~~~~~~~~~~~~~ + +Another common case is the declaration of automatic variables. These are +preferably shown in columns of type and variable name. + +## 4.2 Blank Lines ## {#blank_lines} + +### 4.2.1 Function Declarations ### {#function_declarations} +There should be 1 blank line above a function declaration in a class +file if that function declaration is presented with a Javadoc comment. +This is consist with the statement above about blank lines above +comments. + +### 4.2.2 Function Definitions ### {#function_definitions} +Function definitions in *.cpp files will not typically be accompanied by +any comment, since those are normally only in the header file. It is +desirable to set off the function definition within the *.cpp file by +leaving two blank lines above the function definition. + +### 4.2.3 If Statements ### {#if_statements} +There should be one blank line above if statements. + +## 4.3 Line Length ### {#line_length} +The maximum line width is 99 columns. An exception to this is a long +quoted string such as the internationalized text required to satisfy +MSVC++, described below. + +## 4.4 Strings ## {#strings} +The KiCad project team no longer supports compiling with Microsoft +Visual C++. When you need to break long strings into smaller substrings, +please use the C99 compliant method for improved readability. Using +any of previously accepted methods defined below for breaking +long internationalized strings will no longer be accepted. + +**Examples** +~~~~~~~~~~~~~{.cpp} + // This works with C99 compliant compilers is the **only** accepted method: + wxChar* foo = _( “this is a long string broken ” + “into pieces for readability.” ); + + // This works with MSVC, breaks POEdit, and is **not** acceptable: + wxChar* foo = _( “this is a long string broken ” + L“into pieces for readability” ); + + // This works with MSVC, is ugly, and is **not** accepted: + wxChar* foo = _( “this is a long string \ + broken into pieces for readability” ); +~~~~~~~~~~~~~ + +A second acceptable solution is to simply put the text all on one +line, even if it exceeds the 99 character line length limit. However, +the preferred method is to break strings within the 99 character limit +whenever possible to prevent wrapping. + +## 4.5 Trailing Whitespace ## {#trailing_whitespace} +Many programming editors conveniently indent your code for you. Some of +them do it rather poorly and leave trailing whitespace. Thankfully, most +editors come with a remove trailing whitespace macro or at least a +setting to make trailing whitespace visible so you can see it and +manually remove it. Trailing whitespace is known to break some text +parsing tools. It also leads to unnecessary diffs in the version control +system. Please remove trailing whitespace. + +## 4.6 Multiple Statements per Line ## {#multiple_statements_per_line} +It is generally preferred that each statement be placed on its own line. +This is especially true for statements without keywords. + +**Example** +~~~~~~~~~~~~~{.cpp} + x=1; y=2; z=3; // Bad, should be on separate lines. +~~~~~~~~~~~~~ + +## 4.7 Braces ## {#braces} +Braces should be placed on the line proceeding the keyword and indented +to the same level. It is not necessary to use braces if there is only a +single line statement after the keyword. In the case of if..else +if..else, indent all to the same level. + +**Example** +~~~~~~~~~~~~~{.cpp} + void function() + { + if( foo ) + { + statement1; + statement2; + } + else if( bar ) + { + statement3; + statement4; + } + else + statement5; + } +~~~~~~~~~~~~~ + +## 4.8 Parenthesis ## {#parenthesis} +Parenthesis should be placed immediately after function names and +keywords. Spaces should be placed after the opening parenthesis, before +the closing parenthesis, and between the comma and the next argument in +functions. No space is needed if a function has no arguments. + +**Example** +~~~~~~~~~~~~~{.cpp} + void Function( int aArg1, int aArg2 ) + { + while( busy ) + { + if( a || b || c ) + doSomething(); + else + doSomethingElse(); + } + } +~~~~~~~~~~~~~ + +## 4.9 Switch Formatting ## {#switch} +The case statement is to be indented to the same level as the switch. + +**Example** +~~~~~~~~~~~~~{.cpp} + switch( foo ) + { + case 1: + doOne(); + break; + case 2: + doTwo(); + // Fall through. + default: + doDefault(); + } +~~~~~~~~~~~~~ + + +# 5. License Statement # {#license_statement} +There is a the file copyright.h which you can copy into the top of +your new source files and edit the \<author\> field. KiCad depends on +the copyright enforcement capabilities of copyright law, and this +means that source files must be copyrighted and not be released into +the public domain. Each source file has one or more owners. + + +# 6. Header Files # {#header_files} +Project \*.h source files should: + +- contain a license statement +- contain a nested include \#ifndef +- be fully self standing and not depend on other headers that are not + included within it. + +The license statement was described above. + +## 6.1 Nested Include #ifndef ## {#nested_include} +Each header file should include an \#ifndef which is commonly used to +prevent compiler errors in the case where the header file is seen +multiple times in the code stream presented to the compiler. Just +after the license statement, at the top of the file there should be +lines similar to these (but with a filename specific token other than +`RICHIO_H_`): + +~~~~~~~~~~~~~{.cpp} + #ifndef RICHIO_H_ + #define RICHIO_H_ +~~~~~~~~~~~~~ + +And at the very bottom of the header file, use a line like this one: + +~~~~~~~~~~~~~{.cpp} + #endif // RICHIO_H_ +~~~~~~~~~~~~~ + +The \#ifndef wrapper begins after the license statement, and ends at +the very bottom of the file. It is important that it wrap any nested +\#include statements, so that the compiler can skip them if the +\#ifndef evaluates to false, which will reduce compilation time. + +## 6.2 Headers Without Unsatisfied Dependencies ## {#header_depends} +Any header file should include other headers that it depends on. (Note: +KiCad is not at this point now, but this section is a goal of the +project.) + +It should be possible to run the compiler on any header file within the +project, and with proper include paths being passed to the compiler, the +header file should compile without error. + +**Example** + + $ cd /svn/kicad/testing.checkout/include + $ g++ wx-config --cxxflags -I . xnode.h -o /tmp/junk + +Such structuring of the header files removes the need within a client +\*.cpp file to include some project header file before some other project +header file. (A client \*.cpp file is one that intends to **use, not +implement,** the public API exposed within the header file.) + +Client code should not have to piece together things that a header file +wishes to expose. The exposing header file should be viewed as a fully +sufficient **ticket to use** the public API of that header file. + +This is not saying anything about how much to expose, only that that +which is exposed needs to be fully usable merely by including the header +file that exposes it, with no additional includes. + +For situations where there is a class header file and an +implementation \*.cpp file, it is desirable to hide as much of the +private implementation as is practical and any header file that is not +needed as part of the public API can and should be included only in +the implementation \*.cpp file. However, the number one concern of +this section is that client (using) code can use the public API which +is exposed in the header file, merely by including that one header +file. + + +# 7. I Wrote X Lines of Code Before I Read This Document # {#x_lines} +It's OK. We all make mistakes. Fortunately, KiCad provides a +configuration file for the code beautifier uncrustify. Uncrustify won't +fix your naming problems but it does a pretty decent job of formatting +your source code. There are a few places where uncrustify makes some +less than ideal indentation choices. It struggles with the string +declaration macros wxT(“”) and \_(“”) and functions used as arguments to +other functions. After you uncrustify your source code, please review the +indentation for any glaring errors and manually fix them. See the +uncrustify [website][uncrustify] for more information. + +[uncrustify]: http://uncrustify.sourceforge.net/ + + +# 8. Show Me an Example # {#show_me_an_example} +Nothing drives the point home like an example. The source file richio.h +below was taken directly from the KiCad source. + +~~~~~~~~~~~~~{.cpp} + /* + * This program source code file is part of KICAD, a free EDA CAD application. + * + * Copyright (C) 2007-2010 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com> + * Copyright (C) 2007 KiCad Developers, see change_log.txt for contributors. + * + * This program is free software; you can redistribute it and/or + * modify it under the terms of the GNU General Public License + * as published by the Free Software Foundation; either version 2 + * of the License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, you may find one here: + * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html + * or you may search the http://www.gnu.org website for the version 2 license, + * or you may write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA + */ + + #ifndef RICHIO_H_ + #define RICHIO_H_ + + + // This file defines 3 classes useful for working with DSN text files and is named + // "richio" after its author, Richard Hollenbeck, aka Dick Hollenbeck. + + + #include <string> + #include <vector> + + // I really did not want to be dependent on wxWidgets in richio + // but the errorText needs to be wide char so wxString rules. + #include <wx/wx.h> + #include <cstdio> // FILE + + + + /*/** */* + * Struct IOError + * is a class used to hold an error message and may be used to throw exceptions + * containing meaningful error messages. + */ + struct IOError + { + wxString errorText; + + IOError( const wxChar* aMsg ) : + errorText( aMsg ) + { + } + + IOError( const wxString& aMsg ) : + errorText( aMsg ) + { + } + }; + + + /*/** */* + * Class LINE_READER + * reads single lines of text into its buffer and increments a line number counter. + * It throws an exception if a line is too long. + */ + class LINE_READER + { + protected: + + FILE* fp; + int lineNum; + unsigned maxLineLength; + unsigned length; + char* line; + unsigned capacity; + + public: + + /*/** */* + * Constructor LINE_READER + * takes an open FILE and the size of the desired line buffer. + * @param aFile An open file in "ascii" mode, not binary mode. + * @param aMaxLineLength The number of bytes to use in the line buffer. + */ + LINE_READER( FILE* aFile, unsigned aMaxLineLength ); + + ~LINE_READER() + { + delete[] line; + } + + /* + int CharAt( int aNdx ) + { + if( (unsigned) aNdx < capacity ) + return (char) (unsigned char) line[aNdx]; + return -1; + } + */ + + /*/** */* + * Function ReadLine + * reads a line of text into the buffer and increments the line number + * counter. If the line is larger than the buffer size, then an exception + * is thrown. + * @return int - The number of bytes read, 0 at end of file. + * @throw IOError only when a line is too long. + */ + int ReadLine() throw (IOError); + + operator char* () + { + return line; + } + + int LineNumber() + { + return lineNum; + } + + unsigned Length() + { + return length; + } + }; + + + + /*/** */* + * Class OUTPUTFORMATTER + * is an interface (abstract class) used to output ASCII text in a convenient + * way. The primary interface is printf() like but with support for indentation + * control. The destination of the 8 bit wide text is up to the implementer. + * If you want to output a wxString, then use CONV_TO_UTF8() on it before passing + * it as an argument to Print(). + * <p> + * Since this is an abstract interface, only classes derived from this one + * will be the implementations. + */ + class OUTPUTFORMATTER + { + + #if defined(__GNUG__) // The GNU C++ compiler defines this + + // When used on a C++ function, we must account for the "this" pointer, + // so increase the STRING-INDEX and FIRST-TO_CHECK by one. + // See http://docs.freebsd.org/info/gcc/gcc.info.Function_Attributes.html + // Then to get format checking during the compile, compile with -Wall or -Wformat + #define PRINTF_FUNC __attribute__ ((format (printf, 3, 4))) + + #else + #define PRINTF_FUNC // nothing + #endif + + public: + + /*/** */* + * Function Print + * formats and writes text to the output stream. + * + * @param nestLevel The multiple of spaces to preceed the output with. + * @param fmt A printf() style format string. + * @param ... a variable list of parameters that will get blended into + * the output under control of the format string. + * @return int - the number of characters output. + * @throw IOError, if there is a problem outputting, such as a full disk. + */ + virtual int PRINTF_FUNC Print( int nestLevel, const char* fmt, ... ) throw( IOError ) = 0; + + /*/** */* + * Function GetQuoteChar + * performs quote character need determination. + * It returns the quote character as a single character string for a given + * input wrapee string. If the wrappee does not need to be quoted, + * the return value is "" (the null string), such as when there are no + * delimiters in the input wrapee string. If you want the quote_char + * to be assuredly not "", then pass in "(" as the wrappee. + * <p> + * Implementations are free to override the default behavior, which is to + * call the static function of the same name. + + * @param wrapee A string that might need wrapping on each end. + * @return const char* - the quote_char as a single character string, or "" + * if the wrapee does not need to be wrapped. + */ + virtual const char* GetQuoteChar( const char* wrapee ) = 0; + + virtual ~OUTPUTFORMATTER() {} + + /*/** */* + * Function GetQuoteChar + * performs quote character need determination according to the Specctra DSN + * specification. + + * @param wrapee A string that might need wrapping on each end. + * @param quote_char A single character C string which provides the current + * quote character, should it be needed by the wrapee. + * + * @return const char* - the quote_char as a single character string, or "" + * if the wrapee does not need to be wrapped. + */ + static const char* GetQuoteChar( const char* wrapee, const char* quote_char ); + }; + + + /*/** */* + * Class STRINGFORMATTER + * implements OUTPUTFORMATTER to a memory buffer. After Print()ing the + * string is available through GetString() + */ + class STRINGFORMATTER : public OUTPUTFORMATTER + { + std::vector<char> buffer; + std::string mystring; + + int sprint( const char* fmt, ... ); + int vprint( const char* fmt, va_list ap ); + + public: + + /*/** */* + * Constructor STRINGFORMATTER + * reserves space in the buffer + */ + STRINGFORMATTER( int aReserve = 300 ) : + buffer( aReserve, '\0' ) + { + } + + + /*/** */* + * Function Clear + * clears the buffer and empties the internal string. + */ + void Clear() + { + mystring.clear(); + } + + /*/** */* + * Function StripUseless + * removes whitespace, '(', and ')' from the mystring. + */ + void StripUseless(); + + + std::string GetString() + { + return mystring; + } + + + //-----<OUTPUTFORMATTER>------------------------------------------------ + int PRINTF_FUNC Print( int nestLevel, const char* fmt, ... ) throw( IOError ); + const char* GetQuoteChar( const char* wrapee ); + //-----</OUTPUTFORMATTER>----------------------------------------------- + }; + + + #endif // RICHIO_H_ +~~~~~~~~~~~~~ + + +# 9. Resources # {#resources} +There are plenty of excellent resources on the Internet on C++ coding +styles and coding do's and don'ts. Here are a few useful ones. In most +cases, the coding styles do not follow the KiCad coding style but there +is plenty of other good information here. Besides, most of them have +some great humor in them enjoyable to read. Who knows, you might even +learn something new. + +- [C++ Coding Standard][cppstandard] +- [Linux Kernel Coding Style][kernel] +- [C++ Operator Overloading Guidelines][overloading] +- [Wikipedia's Programming Style Page][style] + +[cppstandard]:http://www.possibility.com/Cpp/CppCodingStandard.html +[kernel]:http://git.kernel.org/cgit/linux/kernel/git/stable/linux-stable.git/tree/Documentation/CodingStyle +[overloading]:http://www.cs.caltech.edu/courses/cs11/material/cpp/donnie/cpp-ops.html +[style]:http://en.wikipedia.org/wiki/Programming_style diff --git a/Documentation/development/compiling.md b/Documentation/development/compiling.md new file mode 100644 index 0000000..6a5ac92 --- /dev/null +++ b/Documentation/development/compiling.md @@ -0,0 +1,413 @@ +# Building KiCad from Source # +If you are a user and not a developer, please consider using one of the prebuilt packages +of KiCad which can be found at the [download][] page on the [KiCad website][]. Building KiCad +from source is not for the faint of heart and is not recommended unless you have reasonable +software development experience. This document contains the instructions on how to build KiCad +from source on the supported platforms. It is not intended as a guide for installing or building +[library dependencies](#library_dependencies). Please consult you platforms documentation for +installing packages or the source code when building the library dependencies. Currently the +supported platforms are Windows Versions 7-10, just about any version of Linux, and OSX +10.7-10.10. You may be able to build KiCad on other platforms but it is not supported. On +Windows and Linux the [GNU GCC][] is the only supported compiler and on OSX [Clang][] is the +only supported compiler. + +[TOC] + +# Development Tools # {#development_tools} + +Before you begin building KiCad, there are a few tools required in addition to your compiler. +Some of these tools are required to build from source and some are optional. + +## CMake Build Configuration Tool ## {#cmake} + +[CMake][] is the build configuration and makefile generation tool used by KiCad. It is required. + + +## Bazaar Version Control System ## {#bazaar} + +The official source code repository is hosted on [Launchpad][] and requires the [Bazaar][] version +control system in order to create a branch of the latest source. Bazaar is not required if you are +going to build a stable version of KiCad from a source archive. + +## GIT Version Control System ## {#git} + +If you prefer to use [GIT][] for version control, there is a mirror of the official KiCad +repository on [Github][]. GIT is not required if you are going to build a stable version of +KiCad from a source archive. Please note that the Github mirror is read only. Do not submit +pull requests to Github. Changes should be sent to the KiCad developer's [mailing list][] as +an attached patch with [PATCH] at the beginning of the subject. + +## Doxygen Code Documentation Generator ## {#doxygen_section} + +The KiCad source code is documented using [Doxygen][] which parses the KiCad source code files +and builds a dependency tree along with the source documentation into HTML. Doxygen is only +required if you are going to build the KiCad documentation. + +## SWIG Simplified Wrapper and Interface Generator ## {#swig} + +[SWIG][] is used to generate the Python scripting language extensions for KiCad. SWIG is not +required if you are not going to build the KiCad scripting extension. + + +# Library Dependencies # {#library_dependencies} + +This section includes a list of library dependencies required to build KiCad. It does not +include any dependencies of the libraries. Please consult the library's documentation for any +additional dependencies. Some of these libraries are optional depending on you build +configuration. This is not a guide on how to install the library dependencies using you systems +package management tools or how to build the library from source. Consult the appropriate +documentation to perform these tasks. + +## wxWidgets Cross Platform GUI Library## {#wxwidgets} + +[wxWidgets][] is the graphical user interface (GUI) library used by KiCad. The current minimum +version is 3.0.0. However, 3.0.2 should be used whenever possible as there are some known bugs +in prior versions that can cause problems on some platforms. Please note that there are also +some platform specific patches that must be applied before building wxWidgets from source. These +patches can be found in the [patches folder][] in the KiCad source. These patches are named by +the wxWidgets version and platform name they should be applied against. wxWidgets must be built +with the --with-opengl option. If you installed the packaged version of wxWidgets on your system, +verify that it was built with this option. + +## Boost C++ Libraries ## {#boost} + +The [Boost][] C++ library is required only if you intend to build KiCad with the system installed +version of Boost instead of the default internally built version. If you use the system installed +version of Boost, version 1.56 or greater is required. Please note there are some platform +specific patches required to build a working Boost library. These patches can be found in the +[patches folder][] in the KiCad source. These patches are named by the platform name they should +be applied against. + +## GLEW OpenGL Extension Wrangler Library ## {#glew} + +The [OpenGL Extension Wrangler][GLEW] is an OpenGL helper library used by the KiCad graphics +abstraction library [GAL] and is always required to build KiCad. + +## GLUT OpenGL Utility Toolkit Library ## {#glut} + +The [OpenGL Utility Toolkit][GLUT] is an OpenGL helper library used by the KiCad graphics +abstraction library [GAL] and is always required to build KiCad. + +## Cairo 2D Graphics Library ## {#cairo} + +The [Cairo][] 2D graphics library is used as a fallback rendering canvas when OpenGL is no +available and is always required to build KiCad. + +## Python Programming Language ## {#python} + +The [Python][] programming language is used to provide scripting support to KiCad. It only needs +to be install if the [KiCad scripting](#kicad_scripting) build configuration option is enabled. + +## wxPython Library ## {#wxpython} + +The [wxPython][] library is used to provide a scripting console for Pcbnew. It only needs to be +installed if the [wxPython scripting](#wxpython_scripting) build configuration option is enabled. +When building KiCad with wxPython support, make sure the version of the wxWidgets library and +the version of wxPython installed on your system are the same. Mismatched versions have been +known to cause runtime issues. + +# KiCad Build Configuration Options # {#build_opts} + +KiCad has many build options that can be configured to build different options depending on +the availability of support for each option on a given platform. This section documents +these options and their default values. + +## Case Sensitivity ## {#case_sensitive_opt} + +The KICAD_KEEPCASE option allows you to build KiCad so that the string matching for component +names is case sensitive of case insensitive. This option is enabled by default. + +## Advanced Graphics Context ## {#graphics_context_opt} + +The USE_WX_GRAPHICS_CONTEXT option replaces wxDC with wxGraphicsContext for graphics rendering. +This option is disabled by default. Warning: the is experimental and has not been maintained +so use at your own risk. + +## Graphics Context Overlay ## {#overlay_opt} + +The USE_WX_OVERLAY option is used to enable the optional wxOverlay class for graphics rendering +on OSX. This is enabled on OSX by default and disabled on all other platforms. + +## Scripting Support ## {#scripting_opt} + +The KICAD_SCRIPTING option is used to enable building the Python scripting support into Pcbnew. +This options is disabled by default. + +## Scripting Module Support ## {#scripting_mod_opt} + +The KICAD_SCRIPTING_MODULES option is used to enable building and installing the Python modules +supplied by KiCad. This option is disabled by default. + +## wxPython Scripting Support ## {#wxpython_opt} + +The KICAD_SCRIPTING_WXPYTHON option is used to enable building the wxPython interface into +Pcbnew including the wxPython console. This option is disabled by default. + +## Github Plugin ## {#github_opt} + +The BUILD_GITHUB_PLUGIN option is used to control if the Github plugin is built. This option is +enabled by default. + +## Build with Static Libraries ## {#static_lib_opt} + +The KICAD_BUILD_STATIC option is used to build KiCad with static libraries. This option is +used for OSX builds only and is disabled by default. + +## Build with Dynamic Libraries ## {#dynamic_lib_opt} + +The KICAD_BUILD_DYNAMIC option is used to build KiCad with dynamic libraries. This option is +used for OSX only and is disabled by default. + +## Build with System Boost ## {#boost_opt} + +The KICAD_SKIP_BOOST option allow you to use the Boost libraries installed on your system to +be used instead of downloading Boost 1.54 and building a custom version specifically for +building KiCad. It is high recommended that you enable this option on Linux and use Boost +version 1.56 or greater. On other platforms you mileage may vary. This option is disabled +by default. + +## OSX Dependency Builder ## {#osx_deps_opt} + +The USE_OSX_DEPS_BUILDER option forces the build configuration to download and build the +required dependencies to build KiCad on OSX. This option is not longer maintained and most +likely is broken. Use it at your own peril. + +## Setting the Build Version and Repository Name ## {#build_version_opt} + +The KiCad version string is defined by the three CMake variables KICAD_VERSION, KICAD_BRANCH_NAME, +and KICAD_VERSION_EXTRA. Variables KICAD_BRANCH_NAME and KICAD_VERSION_EXTRA are defined as empty +strings and can be set at configuration. Unless the source branch is a stable release archive, +KICAD_VERSION is set to "no-vcs-found". If an optional variable is not define, it is not appended +to the full version string. If an optional variable is defined it is appended along with a leading +'-' to the full version string as follows: + + KICAD_VERSION[-KICAD_BRANCH_NAME][-KICAD_VERSION_EXTRA] + +When the version string is set to "no-vcs-found", the build script automatically creates the +version string information from the [git][] repository information as follows: + + + (2016-08-26 revision 67230ac)-master + | | | + | | branch name, "HEAD" if not on a branch, + | | or "unknown" if no .git present + | | + | abbreviated commit hash, or no-git if no .git + | present + | + date of commit, or date of build if no .git present + +# Getting the KiCad Source Code ## {#getting_src} + +There are several ways to get the KiCad source. If you want to build the stable version you +can down load the source archive from the [KiCad Launchpad][] developers page. Use tar or some +other archive program to extract the source on your system. If you are using tar, use the +following command: + + tar -xzf kicad_src_archive.tar.gz + +If you are contributing directly to the KiCad project on Launchpad, you can create a local +branch on your machine by using the following command: + + bzr branch lp:repo_to_branch + +If you prefer to use [GIT][] as you version control system, you can clone the KiCad mirror on +Github using the following command: + + git clone https://github.com/KiCad/kicad-source-mirror + +Here is a list of source links: + +Stable release archive: https://launchpad.net/kicad/4.0/4.0.0-rc1/+download/kicad-4.0.0-rc1.tar.xz + +Development branch: https://code.launchpad.net/~kicad-product-committers/kicad/product + +Github mirror: https://github.com/KiCad/kicad-source-mirror + +# Building KiCad on Linux # {#build_linux} + +To perform a full build on Linux, run the following commands: + + cd kicad_source_tree + mkdir -p build/release + mkdir build/debug # Optional for debug build. + cd build/release + cmake -DCMAKE_BUILD_TYPE=Release \ + -DKICAD_SCRIPTING=ON \ + -DKICAD_SCRIPTING_MODULES=ON \ + -DKICAD_SCRIPTING_WXPYTHON=ON \ + ../../ + make + sudo make install + +If the CMake configuration fails, determine the missing dependencies and install them on your +system. By default, CMake sets the install path on Linux to /usr/local. Use the +CMAKE_INSTALL_PREFIX option to specify a different install path. + +# Building KiCad on Windows # {#build_windows} + +The preferred Windows build environment is [MSYS2][]. The [MinGW][] build environment is still +supported but it is not recommended because the developer is responsible for building *all* of +the dependencies from source which is a huge and frustrating undertaking. The [MSYS2][] project +provides packages for all of the require dependencies to build KiCad. To setup the [MSYS2][] +build environment, depending on your system download and run either the [MSYS2 32-bit Installer][] +or the [MSYS2 64-bit Installer][]. After the installer is finished, update to the latest +package versions by running the `msys2_shell.bat` file located in the MSYS2 install path and +running the command `pacman -Syu`. If the msys2-runtime package is updated, close the shell +and run `msys2_shell.bat`. + +## MSYS2 the Easy Way ## {#msys2_easy} + +The easiest way to build KiCad using the [MSYS2][] build environment is to use the KiCad +[PKGBUILD][] provided by the MSYS2 project to build package using the head of the KiCad +development branch. To build the KiCad package, run the `msys2_shell.bat` file located in the +MSYS2 install path and run the following commands: + + pacman -S git + mkdir src + cd src + git clone https://github.com/Alexpux/MINGW-packages + cd MinGW-packages/mingw-w64-kicad-git + makepkg-mingw -is + +This will download and install all of the build dependencies, clone the KiCad source mirror +from Github, create both 32-bit and 64-bit KiCad packages depending on your MSYS setup, and +install the newly built KiCad packages. Please note that this build process takes a very +long time to build even on a fast system. + +## MSYS2 the Hard Way ## {#msys2_hard} + +If you do not want to create KiCad packages and prefer the traditional `make && make install` +method of building KiCad, your task is significantly more involved. For 64 bit builds run +the `mingw64_shell.bat` file located in the MSYS2 install path. At the command prompt run the +the following commands: + + pacman -S mingw-w64-x86_64-cmake \ + mingw-w64-x86_64-doxygen \ + mingw-w64-x86_64-gcc \ + mingw-w64-x86_64-python2 \ + mingw-w64-x86_64-pkg-config \ + mingw-w64-x86_64-swig \ + mingw-w64-x86_64-boost \ + mingw-w64-x86_64-cairo \ + mingw-w64-x86_64-glew \ + mingw-w64-x86_64-curl \ + mingw-w64-x86_64-wxPython \ + mingw-w64-x86_64-wxWidgets + cd kicad-source + mkdir -p build/release + mkdir build/debug # Optional for debug build. + cd build/release + cmake -DCMAKE_BUILD_TYPE=Release \ + -G "MSYS Makefiles" \ + -DCMAKE_PREFIX_PATH=/mingw64 \ + -DCMAKE_INSTALL_PREFIX=/mingw64 \ + -DDEFAULT_INSTALL_PATH=/mingw64 \ + -DKICAD_SKIP_BOOST=ON \ + -DKICAD_SCRIPTING=ON \ + -DKICAD_SCRIPTING_MODULES=ON \ + -DKICAD_SCRIPTING_WXPYTHON=ON \ + ../../ + make install + +# Building KiCad on OSX # {#build_osx} + +Building on OSX is challenging at best. It typically requires building dependency libraries +that require patching in order to work correctly. For more information on the complexities of +building KiCad on OSX, see the [OSX bundle build scripts][]. + +Download the wxPython source and build using the following commands: + + cd path-to-wxwidgets-src + patch -p0 < path-to-kicad-src/patches/wxwidgets-3.0.0_macosx.patch + patch -p0 < path-to-kicad-src/wxwidgets-3.0.0_macosx_bug_15908.patch + patch -p0 < path-to-kicad-src/patches/wxwidgets-3.0.0_macosx_soname.patch + patch -p0 < path-to-kicad-src/patches/wxwidgets-3.0.2_macosx_yosemite.patch + patch -p0 < path-to-kicad-src/patches/wxwidgets-3.0.0_macosx_scrolledwindow.patch + mkdir build + cd build + export MAC_OS_X_VERSION_MIN_REQUIRED=10.7 + ../configure \ + --prefix=`pwd`/../wx-bin \ + --with-opengl \ + --enable-aui \ + --enable-utf8 \ + --enable-html \ + --enable-stl \ + --with-libjpeg=builtin \ + --with-libpng=builtin \ + --with-regex=builtin \ + --with-libtiff=builtin \ + --with-zlib=builtin \ + --with-expat=builtin \ + --without-liblzma \ + --with-macosx-version-min=10.7 \ + --enable-universal-binary=i386,x86_64 \ + CC=clang \ + CXX=clang++ + +Build KiCad using the following commands: + + cd kicad-source + mkdir -p build/release + mkdir build/debug # Optional for debug build. + cd build/release + cmake -DCMAKE_C_COMPILER=clang \ + -DCMAKE_CXX_COMPILER=clang++ \ + -DCMAKE_OSX_DEPLOYMENT_TARGET=10.7 \ + -DwxWidgets_CONFIG_EXECUTABLE=path-to-wx-install/bin/wx-config \ + -DKICAD_SCRIPTING=ON \ + -DKICAD_SCRIPTING_MODULES=ON \ + -DKICAD_SCRIPTING_WXPYTHON=ON \ + -DPYTHON_EXECUTABLE=path-to-python-exe/python \ + -DPYTHON_SITE_PACKAGE_PATH=wx/wx-bin/lib/python2.7/site-packages \ + -DCMAKE_INSTALL_PREFIX=../bin \ + -DCMAKE_BUILD_TYPE=Release \ + ../../ + make + make install + +# Known Issues # {#known_issues} + +There are some known issues that are platform and/or dependencie specific. This section provides +a list of the currently known issues when building KiCad. + +## Boost C++ Library Issues ## {#boost_issue} + +As of version 5 of [GNU GCC][], using the default configuration of downloading, patching, and +building of Boost 1.54 will cause the KiCad build to fail. Therefore a newer version of Boost +must be used to build KiCad. If your system has Boost 1.56 or greater installed, you job is +straight forward. Configure your KiCad build using `-DKICAD_SKIP_BOOST=ON`. If your system +does not have Boost 1.56 or greater installed, you will have to download and [build Boost][] +from source. If you are building Boost on windows using [MinGW][] you will have to apply the +Boost patches in the KiCad source [patch folder][]. + + +[download]: http://kicad-pcb.org/download/ +[KiCad website]: http://kicad-pcb.org/ +[KiCad Launchpad]: https://launchpad.net/kicad +[GNU GCC]: https://gcc.gnu.org/ +[Clang]: http://clang.llvm.org/ +[CMake]: https://cmake.org/ +[Launchpad]: https://code.launchpad.net/~kicad-product-committers/kicad/product +[Bazaar]: http://bazaar.canonical.com/en/ +[GIT]: https://git-scm.com/ +[Github]: https://github.com/KiCad/kicad-source-mirror +[Doxygen]: http://www.stack.nl/~dimitri/doxygen/ +[mailing list]: https://launchpad.net/~kicad-developers +[SWIG]: http://www.swig.org/ +[wxWidgets]: http://wxwidgets.org/ +[patches folder]: http://bazaar.launchpad.net/~kicad-product-committers/kicad/product/files/head:/patches/ +[Boost]: http://www.boost.org/ +[GLEW]: http://glew.sourceforge.net/ +[GLUT]: https://www.opengl.org/resources/libraries/glut/ +[Cairo]: http://cairographics.org/ +[Python]: https://www.python.org/ +[wxPython]: http://wxpython.org/ +[MSYS2]: http://msys2.github.io/ +[MSYS2 32-bit Installer]: http://repo.msys2.org/distrib/i686/msys2-i686-20150916.exe +[MSYS2 64-bit Installer]: http://repo.msys2.org/distrib/x86_64/msys2-x86_64-20150916.exe +[PKGBUILD]: https://github.com/Alexpux/MINGW-packages/blob/master/mingw-w64-kicad-git/PKGBUILD +[OSX bundle build scripts]:http://bazaar.launchpad.net/~adamwolf/+junk/kicad-mac-packaging/files +[MinGW]: http://mingw.org/ +[build Boost]: http://www.boost.org/doc/libs/1_59_0/more/getting_started/index.html diff --git a/Documentation/development/road-map.md b/Documentation/development/road-map.md new file mode 100644 index 0000000..c1366da --- /dev/null +++ b/Documentation/development/road-map.md @@ -0,0 +1,834 @@ +# Road Map # + +This document is the KiCad Developer's road map document. It is a living +document that should be maintained as the project progresses. The goal of +this document is to provide an overview for developers of where the project +is headed to prevent resource conflicts and endless rehashing of previously +discussed topics. It is broken into sections for each major component of +the KiCad source code and documentation. It defines tasks that developers +an use to contribute to the project and provides updated status information. +Tasks should define clear objective and avoid vague generalizations so that +a new developer can complete the task. It is not a place for developers to +add their own personal wish list It should only be updated with approval +of the project manager after discussion with the lead developers. + +Each entry in the road map is made up of four sections. The goal should +be a brief description of the what the road map entry will accomplish. The +task section should be a list of deliverable items that are specific enough +hat they can be documented as completed. The dependencies sections is a list +of requirements that must be completed before work can begin on any of the +tasks. The status section should include a list of completed tasks or marked +as complete as when the goal is met. + +[TOC] + +# Project # {#project} +This section defines the tasks for the project related goals that are not +related to coding or documentation. It is a catch all for issues such as +developer and user relations, dissemination of information on websites, +policies, etc. + +## Stable Release ## {#stable_release} +**Goal:** + +Provide a lightweight stable release mechanism that is robust enough to meet +the requirements of Linux packagers and corporate users but avoid the burden +of back porting fixes to a maintenance branch to avoid the additional work for +developers. + +**Task:** +- Devise a process to have some type of reasonably stable release protocol + to provide "stable" releases for Linux distribution packagers and corporate + users. +- Document "stable" release procedure. + +**Dependencies:** +- None + +**Status:** +- Initial planning stages. + + +## Website Improvements ## {#website_improvements} +**Goal:** + +Make the website at www.kicad-pcb.org as the definitive resource for both +users and developers which will provide a single point of reference instead +of the many separate websites currently in used. + +**Task:** +- Define the content and design of the website. +- Implement the new design. + +**Dependencies:** +- None + +**Status:** +- No progress. + + +# General # {#general} +This section defines the tasks that affect all or most of KiCad or do not +fit under as specific part of the code such as the board editor or the +schematic editor. + +## Convert to a Single Process Application. ## {#kiway} +**Goal:** + +Merge common schematic and board code into to separate dynamic objects to allow +Eeschema and Pcbnew to run under a single process. + +**Task:** +- Convert the majority core code in Eeschema and Pcbnew into dynamic libraries. +- Provide a robust method for communicating between code running under a single + process. +- Revise the schematic editor and board editor main windows run under a single + process instead of multiple stand alone applications. +- Design a method for passing information between the dynamic libraries running + under the same process. +- Remove inter-process communications between Eeschema and Pcbnew. + +**Dependencies:** +- None + +**Status:** +- Stage 1 code released. +- Stage 2 in process. + +## User Interface Modernization ## {#wxaui} +**Goal:** + +Give KiCad a more modern user interface with dockable tool bars and windows. +Create perspectives to allow users to arrange dockable windows as they prefer. + +**Task:** +- Take advantage of the advanced UI features in wxAui such as detaching and + hiding. +- Study ergonomics of various commercial/proprietary PCB applications (when + in doubt about any particular UI solution, check how it has been done in a + certain proprietary app that is very popular among OSHW folks and do exactly + opposite). +- Clean up menu structure. Menus must allow access to all features of the + program in a clear and logical way. Currently some functions of Pcbnew are + accessible only through tool bars +- Redesign dialogs, make sure they are following same style rules. +- Check quality of translations. Either fix or remove bad quality translations. +- Develop a global shortcut manager that allows the user assign arbitrary + shortcuts for any tool or action. + +**Dependencies:** +- [wxWidgets 3](#wxwidgets3) + +**Status:** +- No progress. + + +# Build Tools # {#build_tools} +This section covers build tools for both the KiCad source as well as the +custom dependency builds required to build KiCad. + +## Create Separate Build Dependency Project ## {#depends_prj} +**Goal:** + +Move the library dependencies and their patches into a separate project to +developers to build and install them as required instead of requiring them +at build time. Give developers the flexibility to build and/or install +library dependencies as they see fit. Remove them from the KiCad source code +to reduce the build footprint. + +**Task:** +- Create a separate project to build all external dependency libraries that are + currently build from source (Boost, OpenSSL, etc). +- Use CMake to create a package configuration file for each library so the + KiCad find package can pull in header paths, library dependencies, compile + flags, and link flags to build KiCad. +- Use CMake find package to pull external dependencies. +- Remove all build from source dependencies for KiCad source code. + +**Dependencies:** +- None + +**Status:** +- Initial concept discussions. + +## Platform Binary Installers ## {#installers} +**Goal:** + +Provide quality installers for all supported platforms. + +**Task:** +- Bring OSX installer up to the level of the Window's and Linux installers. +- Possible use of CPack to build platform specific installers as long as they + are of the same or better quality than the current independent installers. + +**Dependencies** +- None + +**Status** +- No progress + + +# Common Library # {#common_lib} +This section covers the source code shared between all of the KiCad +applications + +## Unified Rendering Framework ## {#unified_rendering} +**Goal:** + +Provide a single framework for developing new tools. Port existing tools +to the new framework and remove the legacy framework tools. + +**Task:** +- Port wxDC to GAL or get Cairo rendering to nearly the performance of the + current wxDC rendering so that we have a single framework to develop new + tools and we can continue to support systems that don't have a complete + OpenGL stack. + +**Dependencies** +- [Tool framework](http://www.ohwr.org/projects/cern-kicad/wiki/WorkPackages) + +**Status** +- No progress + +## Unified Geometry Library ## {#geometry_lib} +**Goal:** + +Select a single geometry library so that all applications share a common +base for 2D objects. Remove any redundant geometry libraries and code to +clean up code base. + +**Task:** +- Select the best geometry library (Boost, etc.) for the task. +- Port all legacy geometry code to the selected library. +- Remove any unused geometry library code. + +**Dependencies:** +- None + +**Status:** +- In progress as part of push and shove router. + +## Conversion to wxWidgets 3 ## {#wxwidgets3} +**Goal:** + +Stop supporting the version 2 branch of wxWidgets so that newer features +provided by version 3 can be utilized. + +**Task:** +- Make wxWidgets 3 a build requirement. +- Remove all wxWidgets 2 specific code. + +**Dependencies:** +- wxWidgets 3 is widely available on Linux distributions. + +**Status:** +- Build now requires 3.0.0 or greater. + +## Linux Printing Improvements ## {#linux_print} +**Goal:** + +Bring printing on Linux up to par with printing on Windows. + +**Task:** +- Resolve Linux printing issues. + +**Dependencies** +- [wxWidgets 3](#wxwidgets3) + +**Status** +- No progress. + +## Object Properties and Introspection ## {#object_props} +**Goal:** + +Provide an object introspection system using properties. + +**Task:** +- Select existing or develop property system. +- Add definable properties to base objects. +- Create introspection framework for manipulating object properties. +- Serialization of properties to and from files and/or other I/O structures. +- Create tool to edit property name/type/value table. + +**Dependencies:** +- None + +**Status:** +- No progress. + +## Dynamic Library Plugin ## {#plugin_base} +**Goal:** + +Create a base library plugin for handling external file I/O. This will allow +plugins to be provided that are external to the project such as providing solid +model file support (STEP, IGES, etc.) using OpenCascade without making it a +project dependency. + +**Task:** +- Create a plugin to handle dynamically registered plugins for loading and + saving file formats. +- This object should be flexible enough to be extended for handling all file + plugin types including schematic, board, footprint library, component + library, etc. +- See [blueprint](https://blueprints.launchpad.net/kicad/+spec/pluggable-file-io) + on Launchpad for more information. + +**Dependencies:** +- None + +**Status:** +- No progress. + + +# KiCad: Application Launcher # {#kicad} +This section applies to the source code for the KiCad application launcher. + + +# Eeschema: Schematic Editor # {#eeschema} +This section applies to the source code for the Eeschema schematic editor. + +## Coherent SCHEMATIC Object ## {#sch_object} +**Goal:** + +Clean up the code related to the schematic object(s) into a coherent object for +managing and manipulating the schematic. + +**Task:** +- Move most if not all of the code from SCH_SCREEN to the new SCHEMATIC object. +- Add any missing functionality to the SCHEMATIC object. + +**Dependencies:** +- None + +**Status:** +- No progress. + +## Hierarchical Sheet Design ## {#hierarchy_fix} +**Goal:** + +Create a more robust sheet instance design rather than recreating them on the +fly every time sheet information is required. + +**Task:** +- Choose a data structure to contain the sheet hierarchy. +- Create helper class to manipulate the hierarchy data structure. + +**Dependencies:** +- None + +**Status:** +- No progress. + +## Schematic and Component Library Plugin ## {#sch_plugin} +**Goal:** +Create a plugin manager for loading and saving schematics and component +libraries similar to the board plugin manager. + +**Task:** +- Design plugin manager for schematics and component libraries. +- Port the current schematic and component library file formats to use the + plugin. + +**Dependencies:** +- [Dynamic library plugin](#plugin_base) + +**Status:** +- No progress. + +## Graphics Abstraction Layer Conversion ## {#sch_gal} +**Goal:** + +Take advantage of advanced graphics rendering in Eeschema. + +**Task:** +- Port graphics rendering to GAL. + +**Dependencies:** +- None + +**Status:** +- No progress. + +## Port Editing Tools ## {#sch_tool_framework} +**Goal:** + +Use standard tool framework across all applications. + +**Task:** +- Rewrite editing tools using the new tool framework. + +**Dependencies:** +- [GAL port](#sch_gal). + +**Status:** +- No progress. + +## S-Expression File Format ## {#sch_sexpr} +**Goal:** + +Make schematic file format more readable, add new features, and take advantage +of the s-expression capability used in Pcbnew. + +**Task:** +- Finalize feature set and file format. +- Discuss the possibility of dropping the unit-less proposal temporarily to get + the s-expression file format and SWEET library format implemented without + completely rewriting Eeschema. +- Add new s-expression file format to plugin. + +**Dependencies:** +- [Dynamic library plugin](#plugin_base). + +**Status:** +- File format document nearly complete. + +## Implement Sweet Component Libraries ## {#sch_sweet} +**Goal:** + +Make component library design more robust and feature rich. Use s-expressions +to make component library files more readable. + +**Task:** +- Use sweet component file format for component libraries. + +**Dependencies:** +- [S-expression file format](#sch_sexpr). + +**Status:** +- Initial SWEET library written. + +## Component Library Editor Improvements ## {#lib_editor_usability} +**Goal:** + +Make editing components with multiple units and/or alternate graphical +representations easier. + +**Task:** +- Determine usability improvements in the library editor for components with + multiple units and/or alternate graphical representations. +- Implement said useability improvements. + +**Dependencies:** +- None. + +**Status:** +- No progress. + +## Component and Netlist Attributes ## {#netlist_attributes} +**Goal:** +Provide a method of passing information to other tools via the net list. + +**Task:** +- Add virtual components and attributes to netlist to define properties that + can be used by other tools besides the board editor. + +**Dependencies:** +- [S-expression schematic file format](#sch_sexpr). + +**Status:** +- No progress. + +## Net Highlighting ## {#sch_net_highlight} +**Goal:** +Highlight wires, buses, and junctions when corresponding net in Pcbnew is selected. + +**Task:** +- Add communications link to handle net selection from Pcbnew. +- Implement highlight algorithm for net objects. +- Highlight objects connected to net selected in Pcbnew. + +**Dependencies:** +- [GAL port, maybe](#sch_gal). + +**Status:** +- No progress. + +# CvPcb: Footprint Association Tool # {#cvpcb} +This section covers the source code of the footprint assignment tool CvPcb. + +## Footprint Assignment Tool ## +**Goal:** + +Merge the footprint assignment functionality of CvPcb into Eeschema so +footprints can be assigned inside the schematic editor eliminating the need +to launch an separate program. + +**Task:** +- Merge footprint assignment capability into Pcbnew shared library. +- Remove CvPcb as a stand alone tool. +- Add functionality to both the schematic and board editors so users can assign + footprints as they prefer. + +**Dependencies:** +- [Convert to a single process application](#kiway). + +**Status:** +- Initial library conversion committed to product branch. + + +# Pcbnew: Circuit Board Editor # {#pcbnew} +This section covers the source code of the board editing application Pcbnew. + +## Tool Framework ## {#pcb_tool_framework} +**Goal:** + +Unify all board editing tools under a single framework. + +**Task:** +- Complete porting of all board editing tools to new tool framework so they + are available in the OpenGL and Cairo canvases. +- Remove all duplicate legacy editing tools. + +**Dependencies:** +- None + +**Status:** +- Initial porting work in progress. + +## Linked Objects ## {#pcb_linked_objects} +**Goal:** + +Provide a way to allow external objects such as footprints to be externally +linked in the board file so that changes in the footprint are automatically +updated. This will all a one to many object relationship which can pave the +way for real board modules. + +**Task:** +- Add externally and internally linked objects to the file format to allow for + footprints and/or other board objects to be shared (one to many relationship) + instead of only supporting embedded objects (one to one relationship) that + can only be edited in place. + +**Dependencies:** +- None. + +**Status:** +- No progress. + +## Modeling ## {#modeling} +**Goal:** + +Provide improved solid modeling support for KiCad including the file formats +available in OpenCascade. + +**Task:** +- Design plugin architecture to handle loading and saving 3D models. +- Back port existing 3D formats (IDF and S3D) to plugin +- Add STEP 3D modeling capability. +- Add IGES 3D modeling capability. + +**Dependencies:** +- [Dynamic library plugin](#plugin_base). + +**Status:** +- No progress. + +## Push and Shove Router Improvements ## {#ps_router_improvements} +**Goal:** +Add features such as matched length and microwave tools to the P&S router. + +**Task:** +- Determine which features are feasible. +- Look at the recently opened FreeRouter code at + http://www.freerouting.net/fen/download/file.php?id=146 for inspiration. + +**Dependencies:** +- None + +**Status:** +- Match trace length work in progress. + +## Layer Improvements ## {#pcb_layers} +**Goal:** + +Increase the number of usable technical and user defined layers in Pcbnew. + +**Task:** +- Extend the number of copper and mechanical layers. +- Develop a type safe flag set template or adapt something already available. +- Refactor Pcbnew code to use new flag and remove the 32 layer limitation. +- Extend the board file format to handle the additional layers. + +**Dependencies:** +- None + +**Status:** +- Work complete on 32 copper and 32 technical layers is complete. + +## Pin and Part Swapping ## {#pcb_drc} +**Goal:** + +Allow Pcbnew to perform pin and/or part swapping during layout so the user +does not have to do it in Eeschema and re-import the net list. + +**Task:** +- Provide forward and back annotation between the schematic and board editors. +- Define netlist file format changes required to handle pin/part swapping. +- Update netlist file formatter and parser to handle file format changes. +- Develop a netlist comparison engine that will produce a netlist diff that + can be passed between the schematic and board editors. +- Create pin/part swap dialog to manipulate swappable pins and parts. +- Add support to handle net label back annotation changes. + +**Dependencies:** +- [S-expression schematic file format](#sch_sexpr). +- [Convert to a single process application](#kiway). + +**Status:** +- No progress. + +## Intelligent Selection Tool ## {#pcb_selection_tool} +**Goal:** + +Make the selection tool easier for the user to determine which object(s) are +being selected. + +**Task:** +- Determine and define the actual desired behavior. +- Improve ambiguous selections when multiple items are under the cursor or in + the selection bounding box. + +**Dependencies:** +- Tool framework. +- Unified geometry library. + +**Status:** +- Initial design committed to product branch. + +## Clipboard Support ## {#fp_edit_clipboard} +**Goal:** + +Provide clipboard cut and paste for footprints.. + +**Task:** +- Clipboard cut and paste to and from clipboard of footprints in footprint + editor. + +**Dependencies:** +- None + +**Status:** +- No progress. + +## Design Rule Check (DRC) Improvements. ## {#drc_improvements} +**Goal:** + +Create additional DRC tests for improved error checking. + +**Task:** +- Replace geometry code with [unified geometry library](#geometry_lib). +- Remove floating point code from clearance calculations to prevent rounding + errors. +- Add checks for component, silk screen, and mask clearances. +- Add checks for keep out zones. +- Remove DRC related limitations such as no arc or text on copper layers. +- Add option for saving and loading DRC options. + +**Dependencies:** +- [Unified geometry library.](#geometry_lib) + +**Progress:** +- Planning + +## Segment End Point Snapping. ## {#segment_snapping} +**Goal:** + +It is not uncommon for board edge segment end points to inadvertently not +be closed causing issues for the 3D viewer and exporting to different file +formats due the board outline not being a fully enclosed polygon. This +feature would add segment end snapping support to allow the board outline +to be fully enclosed. This feature would only need to be supported by the +GAL rendering. + +**Tasks** +- Mark board edge segment ends with a drag indicator to make it visible to the + user that the segment end does not have an endpoint with any other board edge + segment. +- Allow the user to smap the unconnected segment end to the nearest segment end + point. +- Automatically connect unconnected segments with and additional segment when + opening the 3D viewer or exporting the board to another format. Warn the + user that an addition segment has be added and should be verified. + +**Dependencies:** +- None + +**Progress:** +- Initial discussion. + +## Keepout Zones. ## {#keepout_zones} +**Goal:** + +Add support for keepout zones on boards and footprints. + +**Task:** +- Add keepout support to zone classes. +- Add keepout zone support to board editor. +- Add keepout zone support to library editor. + +**Dependencies:** +- [DRC Improvements.](#drc_improvements) + +**Progress:** +- Planning + + +## Gerber File Attributes ## {#gerber_attributes} +**Goal:** + +Add file attributes to gerber files for defining layer stacks. See +[this](http://www.ucamco.com/files/downloads/file/5/Extending_the_Gerber_Format_with_Attributes.pdf) +document and [this](http://www.ucamco.com/files/downloads/file/22/Kick_Starting_a_Revolution_IPC-2581_Meets_Gerber.pdf) +document for more information. + +**Task:** +- Implement gerber file attributes as an optional setting when plotting gerber + files. + +**Dependencies:** +- None + +**Progress:** +- Done both in Pcbnew and Gerbview. + +## Net Highlighting ## {#pcb_net_highlight} +**Goal:** +Highlight rats nest links and/or traces when corresponding net in Eeschema is selected. + +**Task:** +- Add communications link to handle net selection from Eeschema. +- Implement highlight algorithm for objects connected to the selected net. +- Highlight objects connected to net selected in Eeschema + +**Dependencies:** +- None. + +**Status:** +- No progress. + + +# GerbView: Gerber File Viewer # {#gerbview} + +This section covers the source code for the GerbView gerber file viewer. + +## Graphics Abstraction Layer ## {#gerbview_gal} +**Goal:** + +Graphics rendering unification. + +**Task:** +- Port graphics rendering layer to GAL. + +**Dependencies:** +- None. + +**Status** +- No progress. + +# Documentation # {#documentation} +This section defines the tasks for both the user and developer documentation. + +## Conversion to Markup/down Format ## {#doc_format} +**Goal:** + +Make documentation more VCS friendly and separate document content and +formatting for more uniform formatting across all user documentation. + +**Task:** +- Convert the documentation to a mark up/down language to reduce the VCS + footprint, to be able to actually use the VCS to see what changed, and + improve the formatting consistency. + +**Dependencies:** +- None + +**Status:** +- Started with this document. + +## Grammar Check ## {#doc_grammar} +**Goal:** + +Improve user documentation readability and make life easier to for translators. + +**Task:** +- Review and revise all of the English documentation so that it is update with + the current functionality of the code. +- Translate the update documentation into other languages. + +**Dependencies:** +- None + +**Status:** +- No progress. + +## Maintenance ## {#doc_maintenance} +**Task:** +- Keep screen shots current with the source changes. + +**Dependencies:** +- None. + +**Status:** +- No progress. + +## Convert Developer Documentation to Markup/down Format ## {#dev_doc_format} +**Goal:** + +Improve developers documentation to make life easier for new developers to get +involved with the project. + +**Task:** +- Convert platform build instructions from plain text to new format to be + merged with the developer documentation. +- Convert how to contribute to KiCad instructions from plain text to the new + format to merged with the developer documentation. + +**Dependencies:** +- None. + +**Status:** +- No progress. + + +# Unit Testing # {#unittest} +**Goal:** + +Improve the quality of KiCad and ensure changes do no break existing +capabilities. + +**Task:** +- Explore the possibility of including a C++ unit test framework in addition + to the existing Python framework. +- Create robust enough test coverage to determine if code changes break any + core functionality. + +**Dependencies:** +- Completion of the initial release of this document. + +**Status:** +- In progress. + + +# Circuit Simulation # {#simulation} +**Goal:** + +Provide quality circuit simulation capabilities similar to commercial products. + +**Task:** +- Evaluate and select simulation library (spice, gnucap, qucs, etc). +- Evaluate and select plotting library with wxWidgets support. +- Confirm current spice netlist export is up to the task and add missing + support for simulations. +- Use plotting library to handle simulator output in a consistent manor similar + to LTSpice. +- Develop a tool that allows fine tuning of components on the fly. +- Use plugin for the simulation code to allow support of different simulation + libraries. +- Create a library of simulation components such as voltage source, current + source, current probe, etc. + +**Dependencies:** +- [Dynamic library plugin](#plugin_base). + +**Status:** +- No progress. diff --git a/Documentation/development/stable-release-policy.md b/Documentation/development/stable-release-policy.md new file mode 100644 index 0000000..556b20e --- /dev/null +++ b/Documentation/development/stable-release-policy.md @@ -0,0 +1,80 @@ +# Stable Release Policy # + +This document defines the project requirements that must be satisfied in order to create a new +stable release of the KiCad project. It is designed to be a reference for developers and user's +so that both groups expectations are understood. This document is only to be modified by the +project leader or at the request of the project leader. It should be noted that this policy is +not cast in stone and at any time in the future, should the decision be made by the project at +large that it can be revised to suit the ongoing needs of the project and it's users. + +The current release policy is to support the concept of a lightweight stable release. The goal +is to provide regular stable releases of KiCad without the burden of trying to provide long term +support of a full stable release branch. Therefore, once a new release is created, the only +patches that will be made to the stable release branch will be for bugs that cause KiCad to crash +or possible corruption and/or loss of data. No other changes from the current development branch +will be backported to the last stable release by the project. + +[TOC] + +# Stable Release Interval # {#stable_release_interval} + +The criteria required for new stable releases is based on the developers decision that enough +new features and/or improvements have been made to the current development branch to justify a +new stable release. This decision is completely discretionary and can be proposed at any time +by any developer on the KiCad developers mailing list. Once a request for a new stable release +is made, a consensus must be reached by the primary developers to proceed with the release with +the final decision and announcement being made by the project leader. + + +# Feature Freeze # {#feature_freeze} + +Once the announcement has been made that a new stable release is in effect, the current +development branch is frozen. No new features or potentially disruptive core code changes can +be committed with out approval of the primary developers and/or the project leader. + +# Bug Fixing # {#bug_fixing} + +After the development branch has been frozen, work will continue to fix bugs reported against +the development branch. Bugs will be prioritized based on their severity. All bugs that cause +KiCad to crash or cause loss and/or corruption of data must be fixed. All other bugs must be +evaluated to see if they fit into the scope of the stable release. All bugs that fit into the +scope of the stable release will be tagged and must be fixed. All other bugs will be tagged for +the next stable release and fixed when it is convenient. Once the stable release is officially +announced, the bugs tagged as "Fix Committed" that are relevant to the stable release will be +changed to "Fix Released". + +# User Documentation # {#user_docs} + +The user documentation will be updated to reflect the current changes in the code. This includes +all new features, any behavioral changes to existing features, and all screen shots as required. +Completion of the English version of the user documentation is minimum that is required for +release. Foreign language translations can be released at any time as the become available. + +# Stable Release Series Branch # {#stable_branch} + +Once the primary developers decide that the stable release criteria has been met, a new series +branch will be created from the current product branch on Launchpad. At this time the freeze +will be removed from the product branch and normal development can resume. The stable release +version will be incremented from the previous stable release and tagged in the stable release +branch build configuration. + +# System Installers # {#system_installers} + +To proved the best user experience for platforms that do not have package managers, full system +installers will be provided. Currently this only pertains to Windows and OSX. The full system +installers will include all KiCad binary files, all binary library dependencies, user +documentation, component libraries, 3D model libraries, demo project files, and project template +files. Optionally, the footprint libraries can be included for users who prefer not us use the +GitHub plugin. + +# Source Archives # {#source_archives} + +To provide a convenient method for system packagers to build KiCad from known stable sources, +source archives in the most common formats along with the resulting md5sum checksum will be +added to either the KiCad developer's site on Launchpad or the main website at www.kicad-pcb.org. + +# Stable Release Announcement # {#announcement} + +Once all of the above tasks have been completed, the project leader will post an announcement on +the developers mailing list and the Launchpad site. This announcement should include a list of +new features and improvements made since the previous stable release. |