Professional Documents
Culture Documents
Coide Dev Manual
Coide Dev Manual
Manual V2.0
Table of Contents
1. Introduction
2. How to Contribute to this Manual
3. Getting-Started
i. Download and Install CoIDE
ii. Getting Start
iii. Support Device & Debugger
4. Project-Management
i. Project Configuration
5. Component-Workflow
i. Component Definition
ii. Component Coding Conventions
iii. CoIDE Component Workflow
iv. Component-Development-Thought
6. Create-a-Component
i. Create Component Example
ii. Detailed Introduction
7. Maintain-a-Component
8. Document-for-Code
i. CoIDE Markdown Formatting Syntax
ii. Use Markdown in Doxygen
9. Compiler
i. Select GCC path
ii. Compile Output
2
CoIDE Manual V2.0
CoIDE is a free integrated development environment focusing on ARM Cortex-M0/M0+/M3/M4 based microcontrollers. It
uses GCC (GCC-ARM-Embedded) tool chain, and is based on Eclipse, but has been customized and simplified to give
users a minimalism experience. With a powerful code component sharing and collaborative cloud platform Git integrated,
over 800 code components are within easy reach, allowing users to implement programs simply by stacking up building
blocks.
You can also view the online version of this document on http://www.coocox.org/book/coocox/coide-dev-manual.en
Contact us:
Introduction 3
CoIDE Manual V2.0
If anyone want to contribute to this manual, you can download the whole document through Git. The repository url is:
http://www.coocox.org/git/coocox/coide-dev-manual.en.git. The account and password is your CooCox account and
password.
This manual is written in markdown. If you don't know how to write markdown language, read chapter: 07-Document-for-
Code
Currently, you cannot modify the pages on web or upload to coocox server directly, you can send your modification to
master@coocox.com. We will check the modification and add them to the manual.
Before downloading, users need to register for a CooCox account then log in the web site of CooCox, downloading and
using the CoIDE do not charge any fees.
4. You can click on the "Terms of Use" to check the terms of use
8. Erection sequence shows the progress of the installation and product's introduction
9. Installation is complete
Note : Don't forget to configure the GCC toolchain after installation . See: Compiler Setting.
C:\CooCox\CoIDE_V2Beta
C:\Users\%USERNAME%\CoIDE\workspace
C:\Users\%USERNAME%\Appdata\Roaming\CooCox\CoIDE
Corresponding
Quick Start
To create a simple embedded application using CooCox CoIDE, you will perform the following steps: (Before that, do not
forget to configure the GCC compiler and debugger).
Next we will show you an example to introduce how to set up new projects and debugging on COIDE.
Getting Start 11
CoIDE Manual V2.0
Getting Start 12
CoIDE Manual V2.0
Step 6 Input project name. You can also modify the Project Path
Getting Start 13
CoIDE Manual V2.0
Step 7 After clicking "Finish", CoIDE will create a project for you, then we can view components to select which is
needed.
Getting Start 14
CoIDE Manual V2.0
Step 10 After clicking "Add", CoIDE will add the component and it's dependence components to project for you. If we
need anther component, we need click "On-chip peripherals".
Getting Start 15
CoIDE Manual V2.0
Step 11 Click the name of the component can view components related document information
Getting Start 16
CoIDE Manual V2.0
Getting Start 17
CoIDE Manual V2.0
Step 16 Click the "Build" button to compile and link the program
Getting Start 18
CoIDE Manual V2.0
Getting Start 19
CoIDE Manual V2.0
Step 19 If debugging is launched successfully, CoIDE will enter the debug mode. Press F10 can step to run the
program
Step 20 Double-click on the left of the code line number area can set breakpoints
Getting Start 20
CoIDE Manual V2.0
Step 21 Click on the "Varibles", We can see the value of a variable process
Step 22 Click on the "red button", We can exit the debug mode
Getting Start 21
CoIDE Manual V2.0
Note: Here We use Nuvoton NUC472HI8AE as the example, you may need to change the chip according to the device at
hand.
Getting Start 22
CoIDE Manual V2.0
Support list
Freescale
KL0x
Nuvoton
M051
NUC440
NXP
LPC1100LV
LPC1751, LPC1752, LPC1754, LPC1756, LPC1758, LPC1759, LPC1763, LPC1764, LPC1765, LPC1766,
LPC1767, LPC1768, LPC1769
Spansion
MB9BF16x
MB9BF36x
ST
STM32F030 Series
STM32F058C8U6, STM32F058R8T6
STM32F071 Series
STM32L062K8T6, STM32L062K8U6
STM32FL063 Series
STM32L063C8T6, STM32L063R8T6
STM32L100 Series
STM32L152ZET6
STM32L162 Series
Toshiba
TMPM037
TMPM037FWUG
TMPM061
TMPM061FWFG
TMPM330
TMPM330FDFG, TMPM330FWFG, TMPM330FYFG
TMPM332
TMPM332FWUG
TMPM333
TMPM333FDFG, TMPM333FWFG, TMPM333FYFG
TMPM341
TMPM341FDXBG, TMPM341FYXBG
TMPM342
TMPM342FYXBG
TMPM343
TMPM343F10XBG, TMPM343FDXBG, TMPM343FEXBG
TMPM361
TMPM361F10FG, TMPM361FDFG, TMPM361FYFG
TMPM362
TMPM362F10FG
TMPM363
TMPM363F10FG
TMPM364
TMPM364F10FG
TMPM365
TMPM365FWXBG, TMPM365FYXBG
TMPM366
TMPM366FDFG, TMPM366FDXBG, TMPM366FWFG, TMPM366FWXBG, TMPM366FYFG, TMPM366FYXBG
TMPM367
TMPM367FDFG, TMPM367FDXBG, TMPM367FWFG, TMPM367FWXBG, TMPM367FYFG, TMPM367FYXBG
TMPM368
TMPM368FDFG, TMPM368FDXBG, TMPM368FWFG, TMPM368FWXBG, TMPM368FYFG, TMPM368FYXBG
TMPM369
TMPM369FDFG, TMPM369FDXBG, TMPM369FYFG, TMPM369FYXBG
TMPM36B
TMPM36BF10FG, TMPM36BFYFG
TMPM370
TMPM370FYDFG, TMPM370FYFG
TMPM372
TMPM372FWFG, TMPM372FWUG
TMPM373
TMPM373FWDUG
TMPM374
TMPM374FWUG
TMPM375
TMPM375FSDMG
TMPM376
TMPM376FDDFG, TMPM376FDFG
TMPM377
TMPM377FYDFG, TMPM377FYFG
TMPM395
TMPM395FWAXBG
Supported Adapters
List of debug adapters, supported by CoIDE
Debugging
Available Devices PC USB Driver
Adapter
Nu-Link, Nu-
Link-Me or Nuvoton, details Don't need
Nu-Link-pro
ST-Link or ST-
ST, details ST-Link/V2 Driver
Link/V2
Open-
SDA(How to Freescale, details Don't need
use)
Hardware requirements:
Software requirements:
Introduction
Click Configuration button to open project configuration view.
Configuration area is divided into six different configuration items: Compile, Link, Output, User, Debugger and Download.
The first four configurations are building and linking configurations, the last two are debugging/programming configurations.
Compile configuration
1) Option area:
a) FPU: Select MCU type, it includes Not use FPU, FPU soft and FPU hard(Note: If you select the FPU hard, you need
to enable FPU module in the code)
Project Configuration 33
CoIDE Manual V2.0
b) Optimization: Select the level of optimization, it includes (None(-O0), Optimize(-O1), Optimize More(-O2), Optimize
Most(-O3), Optimize Size(-Os))
The added paths will be associated to the current path of the project file to be processed.
Link configuration
Project Configuration 34
CoIDE Manual V2.0
1) Options area:
a) Use Memory Layout from Memory Window (Checked by default)
Check: Memory Area will be available; Scatter File Area will be unavailable.
Mean to use memory Area memory data, and use IDE default link file (such as link.ld).
The system will add default link.ld/arm-gcc-link.ld and file in the directory of the project file, at the same time, the link file
path is filled into the Scatter File area, and user can select a custom link file in the Scatter File area.
Allow recovery of unused input section. Segments that contain the entrance symbol and all the segments of undefined
symbols in the command line will be retained. Segments that contain a dynamic object reference symbol will also be
retained. Check this option to reduce code size.
Project Configuration 35
CoIDE Manual V2.0
Do not use the standard system startup files when linking. The standard system
Select link library: Not use C Library, Use base C Library, Use nano C Library*, Semihosting, Retarget
Only work if you are using gcc-arm-none-eabi-4_7 or higher version. If you choose "Use nano C Library", it will provide two
more options "Printf float" and "Scanf float". Just like the following picture.
Library is collection of a series of procedures, external function and variables. It is integrated into an application program by
the compiler and linker during compilation, and made into a target file and an executable file that can run independently.
The CoIDE library is the GCC library. The extended name of CoIDE Library is .a.
3) Memory Area
The memory area is only available when "Use Memory Layout from Memory Window") is checked.
b) In "Memory Area", start address and size for IROM and IRAM can be customized:
IROM and IRAM start address and size is automatically changed according to your choice, or you can manually modify
these values.
c) In Start line, IROM and IRAM start address can be customized; in Size line, IROM and IRAM size can be customized.
Project Configuration 36
CoIDE Manual V2.0
Output configuration
The configuration area of output files after building project.
The files generated after building a project will be saved under a directory named with the formation of Executable+"/"+
Project Configuration 37
CoIDE Manual V2.0
Name of Executable.
1) Name of Executable: Specify the folder of the output files, the default is the configuration name of the current project
configuration;
3) Create Executable(.elf): Generate. elf executable files, by check / uncheck decide whether to generate the HEX or BIN
file
User configuration
Customize IDE implementation program Before Build, After Build and Before Debug.
In Before Build/Rebuild area implementation program before Build/Rebuild can be customized; in After Build/Rebuild
Project Configuration 38
CoIDE Manual V2.0
You can directly enter commands, or import. bat or. exe files. After configuration, you need build or rebuild the project.
Note:If you enter command directly, you can use Buildin Variables, you can click "Buildin Variables" link to open the
reference document from C:\CooCox\CoIDE\CoIDEHelpFileDir\buildin variables.mht
In Before Debug, if "Auto Compile Before Debugging" is checked, CoIDE will automatically execute incremental compile
before debugging launched.
Debugger configuration
1) Hardware area
a) Adapter: CoIDE supports Colink, CoLinkEx, CMSIS-DAP, Nu-Link, ST-Link, J-Link and some FTDI-compatible adapter.
Project Configuration 39
CoIDE Manual V2.0
c) Max Clock (Hz): You can select the clock frequency from 2M, 1M, 500K, 300K and 100K.
2) Startup area
Select whether to run to main function when you start debug.
3) Advance area
a) Reset Mode: There are three reset modes: HW RESET, VECTRESET and SYSRESETREQ.
4) TargetInfo area
Target Info area displays the host name and port number.
Project Configuration 40
CoIDE Manual V2.0
Download configuration
Project Configuration 41
CoIDE Manual V2.0
7) Add..., Remove and Default are used to configure Flash algorithm file.
Note: If you select J-Link as adapter, Download configuration will be unavailable. J-Link do not use the parameter of
download configuration, that is different from other adapter.
Project Configuration 42
CoIDE Manual V2.0
Component Definition
What is a component?
In order to be better accustomed to faster development and to better leverage the module development, CooCox came up
with the idea of "component development".
Source code. It refers to reusable code, so we need to extract the variable part into component configuration.
Document, including comments within the source code, component homepage, even user manual.
Example (a project), to guarantee the ease of use of a component together with the document.
Test (a project), to guarantee the quality of the component.
Catalogue
E:.
components
ahnniu
hd44780
. gitignore
cox.interface.lbr
LCD_HD44780_Driver_Test.coproj
README.md
assets
images
hd44780_commands.gif
hd44780_ddramaddress.gif
ldc1.gif
pdf
doxygen
build.xml
Doxyfile
makefile
assets
images
placeholder
search
mag_sel.png
search_l.jpg
search_m.jpg
search_r.jpg
include
footer.html
header.html
javascripts
resize.js
stylesheets
doxygen.css
navtree.css
style.css
search
search.css
Component Definition 43
CoIDE Manual V2.0
config
layout.xml
helloworld
putstring
hd44780_config.h
putstring.c
README.md
putstring.coproj
Output
doxygen
doxygen.tag
html
LCD_HD44780_Driver_Test
Debug
source
hd44780.c
hd44780.h
hd44780_config.h.example
hw_hd44780.h
test
main.c
hd44780_config.h
Source code
Source code is the essential part of a component. For components with different functions and different sizes, the number
of code lines can vary a lot, from just a few lines to thousands and millions of lines.
However, no matter how many lines there are, the code can be divided into these parts:
Configuration
UI
Implementation
From the last section, we know that source code is uneditable after being added to the project, but the configuration must
be set by users. Therefore, a component should have a configuration template, e.g.:hd44780_config.h.example. Users can
copy the file to the application, rename it and modify the configuration.
Document
To make sure that the generated document is good-looking, we defined conventions for the component comments, mainly
conventions of comments grouping. The group structure is like this:
HD44780
API reference
Enumeration
Component Definition 44
CoIDE Manual V2.0
Hello World
Invoker Configuration
User Manual (optional)
The grouping can be implemented by Doxygen group command. The top-level group is usually the name of the component.
API reference
Enumeration
Hello World
Invoker Configuration
Above are the names displayed in the output documents. Actually, you need to define the groups like this:
Use the unique symbol followed by the name to be displayed in the document.
Generally speaking,
API reference and Enumeration groups are defined in the header files of user interface.
Invoker Configuration group is defined in the configuration file
Hello World group is defined in the example file.
The internal implementation of source code can further use grouping, or not. You can even use library files.
Component Definition 45
CoIDE Manual V2.0
Below are what you need to pay attention to. For details, please refer to our code.
1. Type definitions
1.1 The program needs to be indented with 4 spaces.
1.2 Use spaces instead of TAB to align the code. Note: In different editors, a tab is defined as different numbers of
spaces, which will lead to code disalignment. Using spaces can avoid this issue.
1.3 Blank lines must be used to separate independent program blocks and follow variable declarations.
1.4 Statements with over 80 characters should be written in multiple lines; long expressions need to start a new line at
the low-priority command characters, and the command characters should be the beginning of the new line with
suitable indentation to keep the program neat.
1.5 Statements like if, for, do, while, case, switch, default, etc. should occupy a line, and be surrounded by {} no
matter how long the statement is.
1.6 In a program, the beginning of a function, the declaration of a structure, and a loop should be indented, and the
processing statements in a case command should be indented too.
1.7 The delimiter in a program like { and } should occupy one line, locate in the same column, and be left-aligned
with relative statements. In a program, the beginning of function body, the definition of class and enumeration, and
statements like if, for, do, while, switch, case need to be indented as mentioned above.
1.8 Spaces need to be added before or (and) after the instruction character when there are more than 2 keywords or
variables or constants in the equivalent operation. Closely related instruction characters (e.g. -> ) should have no
spaces in between when there is no equivalent operations.
2. Comments
The file header should list the brief introduction, author, date and license of the file, like this:
//*****************************************************************************
//
//! \file xadc.h
//! \brief Defines and Macros for ADC API.
//! \version V2.0.0
//! \date 9/30/2011
//! \author CooCox
//! \copy
//!
//! Copyright (c) 2011, CooCox
//! All rights reserved.
//!
//! Redistribution and use in source and binary forms, with or without
//! modification, are permitted provided that the following conditions
//! are met:
//!
//! * Redistributions of source code must retain the above copyright
//! notice, this list of conditions and the following disclaimer.
//! * Redistributions in binary form must reproduce the above copyright
//! notice, this list of conditions and the following disclaimer in the
//! documentation and/or other materials provided with the distribution.
//! * Neither the name of the nor the names of its
//! contributors may be used to endorse or promote products derived
//! from this software without specific prior written permission.
//!
//! THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
//! AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
//! IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
//! ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
//! LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
//! CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
//! SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
//! INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
//! CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
//! ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
//! THE POSSIBILITY OF SUCH DAMAGE.
//
//*****************************************************************************
Words start with \ are Doxygen commands, like file, \brief, and \date.
//*****************************************************************************
//
//! \brief Configures an ADC digital comparator.
//!
//! \param ulBase is the base address of the ADC module.
//! \param ulCompID is the ID of the comparator to configure.
//! \param ulConfig is the configuration of the comparator.
//!
//! This function will configure a comparator. The \e ulConfig parameter is
//! the result of xADC_COMP_INT_xxx value. Reference
//! \ref xADC_Comparator_Int_Condition.
//!
//! \note Here are some matters needing attention.
//!
//! \return None.
//
//*****************************************************************************
The sequence should be like this: \brief, \param(optional), details(optional), \note(optional), and \return.
{
...
//
// Get the ADC_CMPRx register address
//
ulCompRegAddr = ulBase + ADC_CMPR0 + (4 * ulCompID);
...
}
//
//! Compare condition is greater or equal
//
#define ADC_COMP_GREATER_EQUAL 0x00000004
//*****************************************************************************
//
//! \addtogroup NUC1xx_ADC_Operation_Mode NUC1xx ADC Operation Mode
//! \brief ADC A/D Converter Operation Mode.
//! @{
//
//*****************************************************************************
...
//*****************************************************************************
//
//! @}
//
//*****************************************************************************
3. Identifiers naming
3.1 Variables are generally named as this: Type prefix + Noun with the first letter capitalized, e.g. egisterValue,
pucBuffer.
long l lValue
short s sValue
char c cChar
struct s sValue
xBoolean b bResult
3.2. typedef definitions are generally named as: t + Noun with the first letter capitalized, e.g. tBoolean.
3.3. Functions are generally named as: Module + Verb with the first letter capitalized, e.g. SysCtlClockSet,
GPIOPinsRead.
3.4. Marco definitions are generally named as: Module + capitalized Noun separated with _ , e.g.
xADC_EVENT_END_CONVERSION.
Coding notices
Try not to use the similar variable names such as ulTmp, ulTmp1.
All the variables need to be initialized.
To modify some bits of a register, you need to follow the standard process of "Reading - Modifying - Writing".
In functions, all return statements should be followed with parentheses, e.g. return (0);
All variables should use uinx_t type. Original data types like int are not recommended.
Tab is not allowed in code. Use spaces for indentation.
Extra spaces are NOT allowed at the end of the code.
All if, switch, and while statements, regardless of the length of the statements, must be followed with braces ( {} )
Use a space after #end, followed by comments of corresponding #if statement.
Generally a code line has about 80 characters, which can be increased to 120 characters according to actual
situations.
All type conversions need to be declared explicitly.
All Macro variables are in capital letters.
Use a space after #define, and then define the Macro's name, and write the definition in column 33. In special situation,
you can write the definitions in other column, but you need to make all the Macro code in the same file start from the
same column.
Peripherals are named as: Peripheral name + ID, e.g. DMA1, DMA2.
Registers are named as: Peripheral name+ _ + Register name, e.g. DMA_CCR1. The register name should be in
accordance with the Reference Manual.
Peripheral APIs are named as: Peripheral name + _ + API function, e.g. DMA_Enable, DMA_Disable.
To classify the peripheral APIs, the APIs should be written according to the orthogonal principle, to reduce the coupling
of different APIs.
e.g. DMA_IntEnable function should has 2 interface parameters (the peripheral base address and the interrupt flag).
Negative example: Functions over-coupled
extern void I2CDMAEnable(unsigned long ulBase, unsigned long ulDMALast);
goto statement can only be used in error handling section of the code
Bugs caused by priority errors: e.g. == has higher priority than & , so you need to add braces in the expression below:
Repos
paulniu
sd.git
ahnniu
fatfs.git
lcd1602.git
usb.git
anonymous
stm32.git
...
The local component library, is a bunch of git bare warehouse,according to the user name,two layer catalogue of the
name of component to organize.
User name needs to be the only one, so is the component in each user name.
The local component library, no rights management,local user / computer users (no matter whether you log in coocox
or not )has the absolute right of control on the local component library in principle.
The source of the local component library: he is Remote warehouse's incomplete copy, or is downloaded from
Remote warehouse;component submitted to the local computer.
As same as the local component library,it is also a bunch of git bare warehouse,according to the user name,two layer
catalogue of the name of component to organize.
The Remote library has a clear user authentication, and rights management system
+ permissions: can let people who need to access, but reading and writing Remote warehouse are unable to visit without a designat
Each user, has his own user space in the Remote end, and the absolute control rights in this space.
The Remote library, has the function of fork, equal to put a copy of someone else's warehouse in remote (no write
permission) in your space, and can continue to maintain, upgrade, such as paul/sd.git - > ahnniu/sd.git, ahnniu is
unable to operate paul's sd component but is able to operate ahnniu/sd.git.
Git's workflow
Centralized workflow
Usually, centralized workflow uses single collaboration model. Warehouse's center server that stores code can accept
codes all the developers submitted. All developers are ordinary nodes, as the consumer of the central hub, the usual work
is synchronized date with the central warehouse.
Due to Git's allowance of using multiple remote warehouse, then developers can build their own public warehouse, write
data and share with others,at the same time, they also can extract others' updated date from their warehouse.Under this
situation, there is usually a blessed repository which represents the official. Developers thus cloned its own public
warehouse,and then pushed their own submission to ask upholder of official warehouse to pull, update, and merge it into
the main project. Upholder also has a clone warehouse in their local place, he can add in your public warehouse as a
remote warehouse, through testing without fault then merges it into the main branch, finally pushes it to the official
warehouse.
This workflow uses most in GitHub web site. People can copy (i.e., clone fork) a project to their own lists, then let it be their
own public repository. Next, submit their own update to the repository, and everyone can see every time update of yours.
The main advantages is that you can continue to work at your own rhythm, without waiting for the maintainers to deal with
your submitted update. For the maintainers, they can also follow their own rhythm, and come to deal with or accept your
contribution at any time.
+ a component of my, joined a very positive contribution, I trust him, release authority, write for him directly
+ a component of others with some problems, does not update, I can do nothing but fork directly then,update and maintain
+ a component of people that the demand is not satisfied, needs to customized it as their own
+When want to contribute some of the code with no authority, this is pull request
directory organization
The following is CoIDE application, a directory tissue sample of component class project
Application Project:
C:.
CoIDE Projects
Application Projects
SD_MSC
README.md
SD_MSC.proj
App
App.c
App2.c
Components
ahnniu
SDCard
stm32_cmsis
paulniu
FatFs
tom
SDFileSys
README.md
HelloWorld
HelloWorld2
SDFileSys_RW
SDFileSys_RW.c
SDFileSys_RW.proj
SourceCode
SDFileSys.c
SDFileSys.h
Test
Suit0
SDFileSys_Test0.c
SDFileSys_Test0.h
Component Project
C:.
CoIDE Projects
Component Projects
SDFileSys
SDFileSys.Comp.Proj
Components
ahnniu
SDCard
stm32_cmsis
new
SDFileSys
README.md
Doc
Reference
image.jpg
HelloWorld
HelloWorld2
SDFileSys_RW
README.md
SDFileSys_RW.c
SDFileSys_RW.proj
SourceCode
SDFileSys.c
SDFileSys.h
Test
Suit0
SDFileSys_Test0.c
SDFileSys_Test0.h
| | SDFileSys.Comp.Proj
paulniu
FatFs
CoIDE sets the path of default storage project, divides into two categories:
component engineering:
new components also store under the Components directory, just user -- > New
HelloWorld is an independent project, the component file it used will be used multiplex by system
engineering, component and HelloWorld, all have README.md, exist under the corresponding root directory
testing norms
testing framework
Only reach the semi automation or automation, can let norms be the fact, otherwise, it is difficult to ask everyone to follow
the paper.
When do you need to create a component? What is the influence of creating a component ? What is his results / the
output?
Motivation
+When you hope a reusable code can be turned into CoIDE components, and reused in other projects
results
+The results of creating a component is that there is other component in the list of components
-Input parameters
+ the path name, used to save the project in the file system
-Output parameters
+ in the specified path, create a git repository (not bare), and some necessary engineering documents
+ component engineering has norms(including directory components, and so on), IDE will be generated in accordance with the norms
When browsering component library, one of components class will trigger creating
components writing
add dependence
+ I am writing a high-level component, it needs to rely on some of the basements, or drive component
* API calls
add a dependence, is just adding, not modifying the dependent components, otherwise, a dependent object has
changed, the relationship of dependence is also not existing
Clone, checkout (Master) components to the Components directory from the local component library,keep the user /
components'structure
Components engineering, directly integrates automatic testing, through this process, the quality of components can be
ensured
Git Commit
This process, is mainly for making the component place into the list of components, thus, the subsequent other projects,
can be imported to components through the way of importing directly.
component's owner
+Currently login user name, if not login,you can prompt the user to login, otherwise anymous user will be used
Name of component
peripheral Library
Driver
if it is Driver, entrance needs to be provided to choice what kind of Driver chip it support. Note: only an Driver
chip can be chose, Driver chip here is a general term and will be refined in the document of Driver chip
Middleware
When Publish is completed to the local, there should have a further tips: whether to publish on the CooCox, several
benefits:
...
entrance
In the components page, Hello World, users should specify the name of Hello World. Note: whether have the same name
with the previous Hello World or not
Process of IDE
Step 1 Clone component to a user directory, containing components that it dependents on, according to the directory
structure of Components
Step 3 README.md and a.C file automatically generate by the project are edited by the user
Step 5 Git commit only when the compiling is passed can commit
Step 6 Push to the distal end (divide into local and server)
modification of component
The component's creation in the same group, just one point:
If the author of the component is the logged in user, then the position of this componen cloned is unchanged, copy remains:
(Componnets/tom/sd), if the author and the current user are not the same person, then clone it to the space of user who
currently logged in, it's similar to the fork, Publish (effects: create in the position of distal end )
Had we ever thought whether the extra time we spent was necessary ? Can we spend less or even no time, to directly
found the drive we developed previously, and use it to our project ? Coocox can tell you that the answer is positive. In order
to help resolve the troubles above, coocox put forward the thinking of component development, and formulated a set of
corresponding norms. Only we follow this norm to develop drive, could we find that when we develop a driver, basically, we
can use it directly next time.
The new component norm here coocox proposed is fully considered that. If our previous file just used the source file and
The factors have been considered when Coocox is specified the component norms, the new component on its using
arranged according to the new component norms is downward compatible. That is, things in the application layer don't
need to modify. At the same time, the arranging of new component documentation does a lot to the component upgrade
Component-Development-Thought 58
CoIDE Manual V2.0
and maintenance.
Hw_component_driver.h
Component_driver.h
Component_driver.c
Component_driver_config.h.example (driver configuration files in good order are stored in template form)
Component_driver.h
Component_driver.c
Why do we need four documents, what about the two more documents, following we will illustrate intensively the reasons
why we do it.
When in the practical use, separate the underlying implementation which is needlessis to care about, then, put it into the
following documents.
Hw_component_driver.h
Component_driver.c
Component-Development-Thought 59
CoIDE Manual V2.0
And in a real project we generally only use one of the interface methods. We can put it's functions into reality, but in the
practical use, only need to configure it into one of working modes. In order to make it convenient when we use it next time.
When develop, we can extract all the useful configuration informations and put them underneath this file.
Component_driver_config.h.example
According to different circuit to select a different configuration template when you need to use it next time, then, you write a
new component_driver_config.h configuration file to join the project.
Component-Development-Thought 60
CoIDE Manual V2.0
To develop a high-quality component drive, the corresponding instruction documents is essential. Here we list all the
software tools that will be used.
You can download component templates in our website website, or use the build-in component project templates from
updated CoIDE. Its very easy to create a component project, same way with creating a normal one. When you select an
IC, CoIDE will create a template for the user after he/she choose New Component Project.
Attention:the name of component project template is also the name of components.
For example,the name the engineer who create the component input is "ILI9325". Clock it, then we will see the documents
we need, what you should is too fulfill the documents.
Detailed Introduction 71
CoIDE Manual V2.0
Click the bottom"Create a Doc",then select "setting", you can check the basic parts of the component.
Detailed Introduction 72
CoIDE Manual V2.0
Among the catalogue of new project, we can find component project template made by CoIDE. Now, lets see the contents
of the template and the relations with catalogue.
assets: they are used to store pictures or PDF quoted by file instruction.
doxygen: they are used to store configuration files and batching files that related to doxygen sorted by
Detailed Introduction 73
CoIDE Manual V2.0
coocox.
helloworld: they are used to store original file of the example project we wrote for components.
output: they are used to store website file formed by doxygen and procedure files formed by compiler.
test: they are used to store original file of the test project we wrote for components.
README md: this file is our introduction file in the component home page.
We can open index.html file under component_driver\output\doxygen\html in the example template to check sorted
document. Here are component pile homepage sorted by component_driver. We can check what we are interested in
through the right side navigation bar.
From this picture it is not hard to find that we divide component file into four parts:
Detailed Introduction 74
CoIDE Manual V2.0
Original file and header file before revising are as shown in the picture below.
On the basic of the former file, we create two files : Hw_ILI9325.h and ILI9325_config.h
We suggest you add annotation for each macro, the format is as follow:
We should emphasize that we use the doxygen annotation style in this place. So here comes a question ,shall we learn the
doxygen annotation style? Coocox tells us, from our experience, to forming pretty doxygen file, there are only four points
we should know.
The macro definition we mentioned is one of them. Easy, right? At the following introduction we will show you another three
points.
Write a Component_config.h.example
We mentioned that this file is used to save related templates of configuration information. But if this component has not
been finished, we suggest you adopt Component_config.h file format and let it be used in the compile of project.
The configuration we mentioned here means a microscopical definition of Macro in a functional way. Mostly ,we will put the
work model and interface information of device into this file. Here are some information about ILI9325.
write a Component.h
This file is a significant one. In order to keep the compatibility with the program we wrote before, we will define the macro
definition,which we may use in application program, in this place. We also have function declaration. We still suggest you
group the function declaration. If you have ever used the third party middleware, we suggest you divide them into three
groups: Downward transplantation related function, upward transplantation related function, the upper function when used
independently.
Detailed Introduction 75
CoIDE Manual V2.0
//*****************************************************************************
//
//! \addtogroup ILI9325_PORT_API Exported function
//! \brief Downward migration is a function of the need to care about the interface
//! @{
//
//*****************************************************************************
void LCD_Port_Configure(void);
void LCD_FSMC_Configure(void);
void ILI9325_WriteREG(u8 Reg, u16 Value);
u16 ILI9325_ReadREG(u8 Reg);
void ILI9325_WriteData(u16 RGB_Code);
u16 ILI9325_ReadData(void);
void Delay_ms(u32 nms);
//*****************************************************************************
//
//! @}
//
//*****************************************************************************
The code above is the second point we prepared for you to use doxygen document filing, that is grouping. Creating a new
group is similar with defining a variable quantity in C language.
"\addtogroup": key of grouping. It is similar to the key in C language, being recognized by doxygen.
"ILI9325_PORT_API": tag of grouping, it is similar to the name of variable quantity in C language.
"Exported function": name of grouping, it is similar to the value of variable quantity in C language.
"\brief": demonstrate parts of key. The instruction we add will be showed when formed a document.
The same with C language, we can only define it rather than valuing it . At this moment, doxygen will check all the original
files automatically and declare here. If they havent been named, doxygen will take group name as the value. And they will
be shown at the navigation bar.
This file is a difficult part. All our functions will be realized here, and we need to add instructions for each function.
//*****************************************************************************
//
//! \brief This function is used to value written in to register
//!
//! \param Reg : ILI9325 Register number
//! Value : The value will write to the register
//!
//! \ref ILI9325_Registers
//!
//! \note None
//!
//! \return None.
//
//*****************************************************************************
void ILI9325_WriteREG(u8 Reg, u16 Value)
{
#if(LCD_USE_DRIVE_MODE == LCD_FSMC_Mode)
{
LCD_REG = Reg;
LCD_RAM = Value;
}
#else
{
#if(LCD_USE_DATA_BUS_MODE == LCD_16_Bit_Mode)
{
}
#else
{
}
#endif
Detailed Introduction 76
CoIDE Manual V2.0
}
#endif
}
The function annotation we use here is the third point we conclude. It is recommended by coocox. One thing we need to
point out is that we explained "\ref ILI9325_Registers ". The advantage of using this is that the interlinkage can be
produced automatically to the related place when creating a document:
"\ref ":doxygen key, used to remind doxygen that you can create a linkage in this place.
"ILI9325_Registers": name of the group that need to be linked to.
Until now, we almost finished documents filing. But we have only one layer for a group directory. Then what we should do is
adding an upper directory for each document. In this action,we must guarantee all the files are in the same group,
otherwise the directory would be in chaos. With the coocox standard for grouping upper layer ,the whole components have
been grouped as following:
ILI9325
API Reference
Exported API
...
Configuration
LCD Size
...
Enumeration
ILI9325 registers
...
Hello World
test example
...
We use the Markdown file at homepage. We use Markdown language to write this homepage.
When writing homepage documents, we should notice:use following statement to tell doxygen which directory should be
choose to put contents in.
@if (DOXYGEN_PROJECT)
@defgroup ILI9325_Component
@endif
So far we almost finish creating a new component. Then lets talk about how to write example project and test project.
We will revise some files under the directory of helloworld. The revised directory files are as following:
helloworld
test_example
ILI9325_config.h ===================> example configure file
Detailed Introduction 77
CoIDE Manual V2.0
When we write the example instruction document, we should change "@defgroup ILI9325_HelloWorld_HelloWorld_1
HelloWorld_1" to the real group tag and name.
Otherwise, the instruction document can not add any component project.
Open command line under doxygen and input "ant",then press the return button.
C:\Users\Sam\Desktop\New_component\ILI9325\doxygen>ant
Click "create doc" button, then click "setting" button, we can check component document in COIDE.
Detailed Introduction 78
CoIDE Manual V2.0
Summary
When we finish the development of the components,we may only developed the functions we need because of time
limitation. However,once we find any bug that should be updated in the project, we must consider how to maintain the
component.
Then comes the introduction of the way we maintain components in the second 1,use the tool GIT; 2, use the COIDE This
two methods are different, if we retain the original project documents. When the program structure of components has a big
change and it related to things about compile, we suggest you use COIDE to maintain. If the things we modify have no
relation with compiling,like revising documents, we can use git to maintain component. If we couldnt find component
original file and it has been revised a lot, then we would use this two methods together.
First, download component project document, find the specific component homepage under the option "component" in the
official website [http://www.coocox.org]
Use git to copy components in the pointed directory, notice to choose the address in http way.
Maintain-a-Component 79
CoIDE Manual V2.0
Revise component project documents: add a blank space in README.md. save after revise, we can see there is a little bit
change about the icon. That is the change of the file.
Maintain-a-Component 80
CoIDE Manual V2.0
Maintain-a-Component 81
CoIDE Manual V2.0
Find the original project file, then click the button "setting "to enter submit interface. If you cant find it , please follow method
1 to download it in the official website.
Maintain-a-Component 82
CoIDE Manual V2.0
When you enter into the setting interface, it will show "component homepage", "code submit page" "component publish
page" automatically, once your mouse slides through the arrowhead. The homepage will be shown, when entering the page
of setting.
Maintain-a-Component 83
CoIDE Manual V2.0
Then click "code"to enter code submit page. First, choose files need to be submitted or click "file name" button to choose
all. After choosing files, click commit button, then the COIDE will show you a pop-up window to record modification
information. Input information and click sure, you can submit it.
Maintain-a-Component 84
CoIDE Manual V2.0
Check component you submit. Click "Repository", then choose "view component repository", you can find the component
you submit.
Maintain-a-Component 85
CoIDE Manual V2.0
**Notice: when you submit, you must guarantee the positions for logging in is in accordance with submitting, otherwise it
would not be capable to see.
Maintain-a-Component 86
CoIDE Manual V2.0
Log in
Maintain-a-Component 87
CoIDE Manual V2.0
Without logging in
After submitting codes, we can choose whether publish component or not. And we need to set basic information of
component before publishing.
Maintain-a-Component 88
CoIDE Manual V2.0
It is almost the same with maintaining your own component. The only difference is that the start component is not the one
created by yourself, but the one downloaded from fork.
Maintain-a-Component 89
CoIDE Manual V2.0
Maintain-a-Component 90
CoIDE Manual V2.0
Comments: This is an introduction of the Markdown formatting syntax involved in CoIDE component document. CoIDE
Markdown editor supports all legal Markdown characters.
Note: If you are not familiar with the Markdown formatting Syntax, the materials below will be of some help.
FILE NAME
Doxygen will show the first first level header as the file name when parsing. To distinguish a file name from a header, we
recommend you to write your file name like this.
HEADERS
Headers use 1-5 hash characters at the start of the line, corresponding to header levels 1-5.
For example:
# This is an H1
## This is an H2
### This is an H3
#### This is an H4
##### This is an H5
will produce:
This is an H1
This is an H2
This is an H3
This is an H4
This is an H5
EMPHASIS
To emphasize a text, wrap it with double asterisks.
For example:
**This is bold text**
*This is italic text*
will produce:
LINKS
[NAME](URL "TITLE")
NAME is the link text, URL is where you want the link to point, and TITLE is a prompt text for the link.
Note: TITLE is an optional item. When a cursor is stayed on the link, the TITLE text, if any, will prompt.
For example:
[CooCox](http://www.coocox.org/images/logo.jpg )
[CooCox](http://www.coocox.org/images/logo.jpg "CooCox")
will produce:
CooCox
CooCox
IMAGES
With the plain syntax of Doxygen and Markdown, you can easily insert images to your document. Below are detailed steps
of how to insert an image and some operation suggestions.
![NAME](URL "TITLE")
Among which:
![CooCox](http://www.coocox.org/images/logo.jpg )
Assume that there is already an image named CooCox_CooCox_Logo_0000 in the Component Doc directory, you can use
the local image directly like this:
![CooCox](CooCox_CooCox_Logo_0000.gif "CooCox")
Notes:
When inserting inline-style images, Doxygen will first copy the images from different sub-directories to the HTML output
directory, and the HTML will quote one level relative paths. When there are too many image resources, image name conflict
may happen. To avoid such kind of problem, we set a rule as below to name the images:
An index number is a decimal double figure specified by users, ranging from 0 to 99.
LISTS
Markdown supports ordered (numbered) and unordered (bulleted) lists.
Ordered lists use numbers followed by periods and list items with a space in between:
[Number][.][Space][List item]
Unordered lists use asterisks followed by a space and then list items: [*][Space][List item]
For example:
An ordered list:
1. Item A
2. Item B
3. Item C
A disordered list:
* Item A
* Item B
* Item C
1. Item A
* Item 1A
* Item 1B
* Item 1C
2. Item B
* Item 2A
* Item 2B
* Item 2C
3. Item C
* Item 3A
* Item 3B
* Item 3C
Will produce:
An ordered list:
1. Item A
2. Item B
3. Item C
A disordered list:
Item A
Item B
Item C
1. Item A
Item 1A
Item 1B
Item 1C
2. Item B
Item 2A
Item 2B
Item 2C
3. Item C
Item 3A
Item 3B
Item 3C
BLOCKQUOTES
Put the > followed by a space before the first line of a paragraph.
Note: Blockquotes can be nested (i.e. a blockquote-in-a-blockquote), and can contain other Markdown elements, including
headers, lists, and code blocks
For example:
Will produce:
Headers in blockquotes
CODE BLOCKS
1. Insert at least 3 wave lines in a row in the line below the code block.
2. followed by the programming language type, {.programming language type}
3. followed by the code block
4. followed by a blank line and then the line of as many wave lines as the first line.
Cautions:
1. The number of wave lines in the first and last line should be the same
2. The programming language type is an optional item
3. All comments in the code block should be marked by "//" characteristic due to Doxygen syntax
If there are lots of comments for the code, you can consider putting them in a separate file, and quote the file in
Readme.md file.
For example:
~~~~~~~~~~{.c}
// Hello, this is a function
printf("Hello world");
~~~~~~~~~~
is used to insert the code printf ("Hello world") written in C and highlight it.
Will produce:
printf("Hello world");
TEXT-FORMATTING
Note: It's used to display some mark or code in a text format
Wrap the mark or code with ', and wrap them with spaces.
For example:
Will produce:
HORIZONTAL RULES
Use three or more underscores, and wrap them with blank lines.
For example:
Press ENTER
---
Press ENTER
Will produce:
1. <br>
2. \n
Note: You can force line feed at any place you want, including within a table.
INLINE HTML
Markdown supports inline HTML, which allows you to create documents in any style you want. Here is one thing you need
to pay special attention to:
The only restrictions Markdown syntax has for inserting HTML are:
Block-level HTML elements e.g. <div> , <table> , <pre> , <p> , etc. must be separated from surrounding
content by blank lines, and the start and end tags of the block should not be indented with tabs or spaces.
Good news is that there is no such restriction as above in Doxygen. You can even insert Markdown formatted content in
HTML blocks.
Note:Although Doxygen won't process content in code block , it will remove the indented spaces and make the code look
disordered. If you need to insert preformatted code in comment or Markdown, it's best to use the <pre> tag or directly
insert a code block.
REFERENCE
markdown tables generator
Open source fans and official API libraries often use Doxygen to add code comments, which can generate documents out
of code. That means, users only need to maintain one code file, and the situation where documents don't match the code at
all can be effectively avoided.
The shortcoming of Doxygen is also very apparent though. The comment syntax is too complex to understand, thus is not
suitable for professional documents.
For many times, we wished to generate documents both good-looking and easy to understand for common people without
complex syntax. Is it possible?
Yes! We have Markdown! Users can focus on the content of the documents and don't need to worry about the form, which
the Markdown editor will take care of.
PHILOSOPHY
Readability, however, is emphasized above all else. A Markdown-formatted document should be publishable as-is, as
plain text, without looking like it's been marked up with tags or formatting instructions. While Markdown's syntax has
been influenced by several existing text-to-HTML filters including Setext, atx, Textile, reStructuredText, Grutatext,
and EtText the single biggest source of inspiration for Markdown's syntax is the format of plain text email.
To this end, Markdown's syntax is comprised entirely of punctuation characters, which punctuation characters have
been carefully chosen so as to look like what they mean. E.g., asterisks around a word actually look like emphasis.
Markdown lists look like, well, lists. Even blockquotes look like quoted passages of text, assuming you've ever used
email.
Looks great! Right? In fact, many documents in github are written in Markdown syntax.
Since Markdown is so useful, it would be even better if it can be used in Doxygen, so we can not only comment the code
conveniently but also write a large professional document without code. We can also use other Markdown editor instead of
Doxygen.
Note: Please make sure you are familiar with basic operation and frequently-used syntax of Doxygen before you read
further. If you have never known anything about Doxygen before, please read the Getting started guide of Doxygen first.
Description {#mainpage}
=======================
## INTRODUCTION
## What to do next?
Let's learn in detail the Markdown syntax and the cautions in Doxygen introduction.
Configure the file with Doxygen settings by default, compile it in current directory, and open the corresponding HTML file, as
shown in the figure below:
Note: Please make sure that the encoding format of the readme.md file is UTF-8
STANDARD MARKDOWN
Now that we know how to use Markdown in Doxygen, let's learn in detail the basic syntax of Markdown.
1. Headers
Markdown supports two types of headers, Setext-type and Atx-type.
Setext-type uses a line under the header containing only ='s (for level 1 header) or -'s (for level 2 header). For example:
Example 1
This is an H1
=============
This is an H2
-------------
Atx-type use one to six #'s at the start of a line to make a header from level 1 to level 6. For example:
Example 2
# This is an H1
## This is an H2
###### This is an H6
You can end a header by any number of #'s, just to make it look good.
Example 3
# This is an H1 #
## This is an H2 ##
Will produce
Example 1
This is an H1
This is an H2
Example 2
This is an H1
This is an H2
This is an H6
Example 3
This is an H1
This is an H2
This is an H3
Cautions
1. For the exact amount of ='s or -'s under Setext-type headers, standard Markdown requires at least one, while Doxygen
requires at least two
2. Doxygen has a special requirement for level 1 headers, please refer to Markdown Extensions for the details.
Note: A line containing nothing but spaces, tabs or carriage returns is considered blank.
1) Insert <br/> in any place of the paragraph 2) Insert more than two spaces at the end of the line
For example
This is a paragraph
This is a paragraph
This is a sentence among the paragraph
Output HTML
This is a paragraph
This is a paragraph with no line breaks, This is a paragraph with no line breaks, This is a paragraph with no line breaks,
This is a paragraph with no line breaks, This is a paragraph with no line breaks
Cautions
1. Common paragraphs should not be indented by spaces or tabs, or it will be treated as "pre-formatted text" by compiler.
2. Doxygen doesn't support breaking a line by ending a line with two or more spaces. When you do need to break a line
in the middle of a paragraph, you can insert a <br/> .
3. Blockquotes
Markdown uses email-style > characters for blockquoting. If you're familiar with quoting passages of text in an email
message, then you know how to create a blockquote in Markdown. It looks best if you hard wrap the text and put a >
before every line:
Example 1
> A Thai satellite has detected some 300 objects in an area of
> the southern Indian Ocean being searched for missing Malaysia
> Airlines flight MH370.
>
> The image was taken by the Thaichote satellite on 24 March,
> a day after images from a French satellite purported to show
> 122 floating objects.
>
> Flight MH370 disappeared on 8 March with 239 people on board.
> No debris has been recovered from the ocean so far.
Markdown allows you to be lazy and only put the > before the first line of a hard-wrapped paragraph:
Example 2
> A Thai satellite has detected some 300 objects in an area of
the southern Indian Ocean being searched for missing Malaysia
Airlines flight MH370.
Example 3
> This is the first level of quoting.
>
> > This is nested blockquote.
>
> Back to the first level.
Blockquotes can contain other Markdown elements, including headers, lists, and code blocks:
Example 4
> ## This is a header
>
> 1. This is first item
> 2. This is second item
>
> Here, Show code snippet for you:
> return shell_exec("echo $input | $markdown_script");
Will produce
Example 1
A Thai satellite has detected some 300 objects in an area of the southern Indian Ocean being searched for missing
Malaysia Airlines flight MH370.
The image was taken by the Thaichote satellite on 24 March, a day after images from a French satellite purported to
show 122 floating objects.
Flight MH370 disappeared on 8 March with 239 people on board. No debris has been recovered from the ocean so
far.
Example 2
A Thai satellite has detected some 300 objects in an area of the southern Indian Ocean being searched for missing
Malaysia Airlines flight MH370.
The image was taken by the Thaichote satellite on 24 March, a day after images from a French satellite purported to
show 122 floating objects.
Flight MH370 disappeared on 8 March with 239 people on board. No debris has been recovered from the ocean so
far.
Example 3
Example 4
This is a header
1. This is first item
2. This is second item
Cautions
1. Doxygen doesn't support omitting > as in Example 2, you need to make sure that each line of the blockquote is started
with a > .
2. In Doxygen, if you want to insert a Markdown code block in a blockquote, you need to guarantee at least one blank line
between the blocks. The code below won't take effect in Doxygen due to lack of blank lines:
4. Lists
Unordered lists use asterisks (*), pluses (+), and hyphens (-) interchangeably as list markers:
Example 1
* Red
* Green
* Blue
OR
+ Red
+ Green
+ Blue
OR
- Red
- Green
- Blue
Example 2
1. Bird
2. McHale
3. Parish
It's important to note that the actual numbers you use to mark the list have no effect on the HTML output Markdown
produces. The HTML Markdown produces from the above list is:
<ol>
<li>Bird</li>
<li>McHale</li>
<li>Parish</li>
</ol>
Example 3
1. Bird
1. McHale
1. Parish
or even:
Example 4
3. Bird
1. McHale
8. Parish
you'd get the exact same HTML output. The point is, if you want to, you can use ordinal numbers in your ordered Markdown
lists, so that the numbers in your source match the numbers in your published HTML. But if you want to be lazy, you don't
have to.
If you do use lazy list numbering, however, you should still start the list with the number 1. At some point in the future,
Markdown may support starting ordered lists at an arbitrary number.
List markers typically start at the left margin, but may be indented by up to three spaces. List markers must be followed by
one or more spaces or a tab.
To make lists look nice, you can wrap items with hanging indents:
Example 5
Example 6
If list items are separated by blank lines, Markdown will wrap the items in <p> tags in the HTML output. For example, this
input:
Example 7
* Bird
* Magic
<ul>
<li>Bird</li>
<li>Magic</li>
</ul>
But this:
Example 8
* Bird
* Magic
<ul>
<li><p>Bird</p></li>
<li><p>Magic</p></li>
</ul>
List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must be indented by either 4
spaces or one tab:
Example 9
mi posuere lectus.
It looks nice if you indent every line of the subsequent paragraphs, but here again, Markdown will allow you to be lazy:
Example 10
To put a blockquote within a list item, the blockquote's > delimiters need to be indented:
Example 11
To put a code block within a list item, the code block needs to be indented twice 8 spaces or two tabs:
Example 12
It's worth noting that it's possible to trigger an ordered list by accident, by writing something like this:
In other words, a number-period-space sequence at the beginning of a line. To avoid this, you can backslash-escape the
period:
Will produce
Example 1
Red
Green
Blue
Example 2, 3, and 4
1. Bird
2. McHale
3. Parish
Example 5 and 6
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
viverra nec, fringilla in, laoreet vitae, risus.
Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.
Example 7
Bird
Magic
Example 8
Bird
Magic
Example 9
1. This is a list item with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi
posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. Donec sit amet nisl. Aliquam semper ipsum sit amet
velit.
Example 11
Example 12
Cautions
Doxygen will treat two list items separated by a blank line as one list item
For an ordered list, Doxygen will handle it in strict accordance with an ascending order. Any same sequence or
descending order will start a new ordered list.
The actual numbers you use to mark the list have no effect on the HTML output Markdown produces.
5. CODE BLOCKS
Pre-formatted code blocks are used for writing about programming or markup source code. Rather than forming normal
paragraphs, the lines of a code block are interpreted literally. Markdown wraps a code block in both <pre> and <code>
tags.
To produce a code block in Markdown, simply indent every line of the block by at least 4 spaces or 1 tab. For example,
given this input:
One level of indentation 4 spaces or 1 tab is removed from each line of the code block. For example, this:
A code block continues until it reaches a line that is not indented (or the end of the article).
Within a code block, ampersands ( & ) and angle brackets ( < and > ) are automatically converted into HTML entities. This
makes it very easy to include example HTML source code using Markdown just paste it and indent it, and Markdown will
handle the hassle of encoding the ampersands and angle brackets. For example, this:
<div class="footer">
© 2004 Foo Corporation
</div>
<pre><code><div class="footer">
&copy; 2004 Foo Corporation
</div>
</code></pre>
Regular Markdown syntax is not processed within code blocks. E.g., asterisks are just literal asterisks within a code block.
This means it's also easy to use Markdown to write about Markdown's own syntax.
Cautions
"To produce a code block in Markdown, simply indent every line of the block by at least 4 spaces or 1 tab."
Note 2 points:
Doxygen and some Markdown editor will replace a tab with a certain number of spaces before processing it, at that time
only spaces stand for an indentation.
In this case, it's really important how many spaces a tab equals to (TAB = N Space). When N equals 4, everything is
normal, and the result matches the expectation; When N is more than 4, the editor will remove 4 spaces, and handle the
rest spaces as part of the code; When N is less than 4, the editor will remove all the spaces first and handle the rest part as
common text.
Note: You can set the number of spaces in a tab by modifying the value of TAB_SIZE in Doxygen project configuration file.
# 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.
# Minimum value: 1, maximum value: 16, default value: 4.
TAB_SIZE = 4
Suggestion: Don't use TAB in your document, and set a tab as 4 spaces in your editor, in this way many potential
problems can be avoided.
The standard Markdown syntax only states that a code block should be indented by 4 spaces, but does not say what the
indentation is relative to. It's relative to the leftmost row of the document by default. We call the indentation relative to the
leftmost row, in spaces, as absolute offset.
Generally the threshold value of absolute offset is 4. If the absolute offset of a paragraph is no more than 4, it will be
handled as a common paragragh. When the absolute offset is over 8, check first if the paragraph is in a list. If yes, treat the
part as a code block in a list, if not, treat the part as a common code block.
We can see that the absolute offset plays a very important role in standard Markdown editors.
Is it the same in Doxygen? No. Because Doxygen handles not only pure Markdown text, but also some Markdown text
inserted in code comment, and comment can has any indentation, which can lead to a problem if there is no special
treatment. Therefore, Doxygen uses relative offset instead of absolute offset, re:
Note: The relative offset in a list does not include the list symbols.
Generally the Doxygen method won't cause any mistake to the text written in Markdown, unless you write it as below:
text indented by 0 space relative to the last paragraph; indented by 0 space relative to the leftmost row.
text indented by 1 space relative to the last paragraph; indented by 1 space relative to the leftmost row.
text indented by 1 space relative to the last paragraph; indented by 2 spaces relative to the leftmost row.
code indented by 2 spaces relative to the last paragraph; indented by 4 spaces relative to the leftmost row.
In this condition, Markdown editors will treat the code line as code while Doxygen won't, because there is only 2 spaces'
relative indentation.
6. HORIZONTAL RULES
You can produce a horizontal rule tag by placing three or more hyphens, asterisks, or underscores on a line by
themselves.
Example 1
***
---
___
Example 2
* * *
- - -
Will produce
[Caution]
1. Standard Markdown Editors support all above standards, but Doxygen requires a horizontal rule tag to be in a single line
wrapped by blank lines. Other editors also have this requirement.
Therefore, we recommend you to use the horizontal rule tag in a single line and wrap it with blank lines, like this:
This is a paragraph
***
---
***
___
instead of this (please pay special attention to the last 3 horizontal rule tags):
This is a paragraph
***
---
***
___
2. For Doxygen, horizontal rule tags will only work in Markdown files. They won't work in code comments.
For example:
/** A list:
* * item1
* *******
* * item2
*/
7. LINKS
To create an inline link, use a set of regular parentheses immediately after the link text's closing square bracket. Inside the
parentheses, put the URL where you want the link to point, along with an optional title for the link, surrounded in quotes. For
example:
Example 1
Will produce:
If you're referring to a local resource on the same server, you can use relative paths:
Reference-style links use a second set of square brackets, inside which you place a label of your choosing to identify the
link:
Example 2
Then, anywhere in the document, you define your link label like this, on a line by itself:
That is:
Square brackets containing the link identifier (optionally indented from the left margin using up to three spaces);
followed by a colon;
followed by one or more spaces (or tabs);
followed by the URL for the link;
optionally followed by a title attribute for the link, enclosed in double or single quotes, or enclosed in parentheses.
NOTE: There is a known bug in Markdown.pl 1.0.1 which prevents single quotes from being used to delimit link titles.
You can put the title attribute on the next line and use extra spaces or tabs for padding, which tends to look better with
longer URLs:
[id]: http://example.com/longish/path/to/resource/here
"Optional Title Here"
Link definitions are only used for creating links during Markdown processing, and are stripped from your document in the
HTML output.
Link definition names may consist of letters, numbers, spaces, and punctuation but they are not case sensitive. E.g.
these two links:
[link text][a]
[link text][A]
are equivalent.
The implicit link name shortcut allows you to omit the name of the link, in which case the link text itself is used as the name.
Just use an empty set of square brackets e.g., to link the word "Google" to the google.com web site, you could simply
write:
[Google][]
[Google]: http://google.com/
Because link names may contain spaces, this shortcut even works for multiple words in the link text:
Link definitions can be placed anywhere in your Markdown document. I tend to put them immediately after each paragraph
in which they're used, but if you want, you can put them all at the end of your document, sort of like footnotes.
Using the implicit link name shortcut, you could instead write:
Both of the above examples Will produce the following HTML output:
For comparison, here is the same paragraph written using Markdown's inline link style:
The point of reference-style links is not that they're easier to write. The point is that with reference-style links, your
document source is vastly more readable. Compare the above examples: using reference-style links, the paragraph itself is
only 81 characters long; with inline-style links, it's 176 characters; and as raw HTML, it's 234 characters. In the raw HTML,
there's more markup than there is text.
With Markdown's reference-style links, a source document much more closely resembles the final output, as rendered in a
browser. By allowing you to move the markup-related metadata out of the paragraph, you can add links without interrupting
the narrative flow of your prose.
Example 1
Example 2
[Caution]
* [Overview](#overview)
* [Installation](#installation)
<h2 id="overview">Overview</h2>
<h2 id="philosophy">Installation</h2>
2. The URL must contain http:// forehead in the link, or the link redirection will fail.
3. Some Markdown editors doesn't support a title enclosed in single quotes, please use enclose the title with double
quotes.
8. EMPHASIS
Markdown treats asterisks ( * ) and underscores ( _ ) as indicators of emphasis. Text wrapped with one * or _ will be
wrapped with an HTML <em> tag; double * 's or _ 's will be wrapped with an HTML <strong> tag. E.g., this input:
Example 1
*single asterisks*
_single underscores_
**double asterisks**
__double underscores__
Will produce:
<em>single asterisks</em>
<em>single underscores</em>
<strong>double asterisks</strong>
<strong>double underscores</strong>
You can use whichever style you prefer; the lone restriction is that the same character must be used to open and close an
emphasis span.
Example 2
un*frigging*believable
But if you surround an * or _ with spaces, it'll be treated as a literal asterisk or underscore.
Example 3
To produce a literal asterisk or underscore at a position where it would otherwise be used as an emphasis delimiter, you
can backslash escape it:
Example 4
Example 1
single asterisks
single underscores
double asterisks
double underscores
Example 2
unfriggingbelievable
Example 3
Example 4
Cautions
Example 2
un*frigging*believable
To use * for emphasis, please ensure a space before the opening asterisk and after the closing asterisk, like this:
un *frigging* believable
un **frigging** believable
To emphasize a word within a word, please directly use <em> or <strong> , like this:
un<em>frigging</em>believable
un<strong>frigging</strong>believable
2. Doxygen can't use * to emphasize Chinese characters, please directly use <em> or <strong> instead.
**Line1
Line2
Line3**
While many compilers don't. In the meantime, almost all editors don't support line breaks.
**Line1
Line2
Line3**
5. In Doxygen, only text enclosed in the * 's which meet following conditions would be processed as emphasis:
Opening asterisk:
Closing asterisk:
Follows: neither a space, a blank line, nor any of the characters ( { [ < = + - \ @
9. CODE
Note: The backtick character is located on left side of the number 1 and on top of Tab on the keyboard. Don't mix it up with
the single quote.
For example:
Example 1
Will produce:
To include a literal backtick character within a code span, you can use multiple backticks as the opening and closing
delimiters:
Example 2
The backtick delimiters surrounding a code span may include spaces one after the opening, one before the closing. This
allows you to place literal backtick characters at the beginning or end of a code span:
Example 3
Will produce:
With a code span, ampersands and angle brackets are encoded as HTML entities automatically, which makes it easy to
include example HTML tags. Markdown will turn this:
Example 4
into:
Example 1
Example 2
Example 3
Example 4
Cautions
2. Editors provide extra processing methods to insert a big amount of code. Below are some common methods:
```
```
Note: GFM (GitHub Flavored Markdown) adopts this method. And you can use some indicators after ``` to highlight the
code.
~~~
~~~
3. Doxygen has special commends for code blocks, please refer to Markdown Extensions for the details.
4. Doxygen can't handle code which includes single quotes like this:
10. IMAGES
Markdown uses an image syntax that is intended to resemble the syntax for links, allowing for two styles: inline and
reference.
![Alt text](/path/to/img.jpg)
That is:
An exclamation mark: ! ;
followed by a set of square brackets, containing the alt attribute text for the image;
followed by a set of parentheses, containing the URL or path to the image, and an optional title attribute enclosed in
double or single quotes.
![Alt text][id]
Where "id" is the name of a defined image reference. Image references are defined using syntax identical to link
references:
For example
Will produce:
Will produce
Cautions
1. Markdown only provide image link mechanism rather than image management. In Doxygen, if the document includes
any link to the local image, you must copy the image to HTML output folder manually to make the image show normally.
2. Please make sure the characters, alt text, and URL are in the same line, otherwise it won't be recognized by Markdown
analyzer.
Markdown supports a shortcut style for creating "automatic" links for URLs and email addresses: simply surround the URL
or email address with angle brackets.
Example 1
<http://www.google.com.cn>
<xxx@gmail.com>
<p><a href="http://www.google.com">http://www.google.com</a></p>
<p><a href="mailto:xxx@gmail.com">xxx@gmail.com</a></p>
Example 1
http://www.google.com.cn
xxx@gmail.com
Cautions
The website must be complete and valid, including http:// or https:// . The code below won't generate correct links:
<www.google.com.cn>
<google.com.cn>
If you are familiar with HTML, simply use HTML itself. There's no need to preface it or delimit it to indicate that you're
switching from Markdown to HTML; you just use the tags.
The only restrictions are that block-level HTML elements e.g. <div> , <table> , <pre> , <p> , etc. must be separated
from surrounding content by blank lines, and the start and end tags of the block should not be indented with tabs or spaces.
Markdown is smart enough not to add extra (unwanted) <p> tags around HTML block-level tags.
<table>
<tr>
<td>1</td>
<td>2</td>
<td>3</td>
</tr>
<tr>
<td>4</td>
<td>5</td>
<td>6</td>
</tr>
<tr>
<td>7</td>
<td>8</td>
<td>9</td>
</tr>
</table>
Note that Markdown formatting syntax is not processed within block-level HTML tags. E.g., you can't use Markdown-style
*emphasis* inside an HTML block.
Span-level HTML tags e.g. <span> , <cite> , or <del> can be used anywhere in a Markdown paragraph, list item, or
header. If you want, you can even use HTML tags instead of Markdown formatting; e.g. if you'd prefer to use HTML <a> or
<img> tags instead of Markdown's link or image syntax, go right ahead.
Unlike block-level HTML tags, Markdown syntax is processed within span-level tags.
1 2 3
4 5 6
7 8 9
Cautions
The only restrictions are that block-level HTML elements e.g. <div> , <table> , <pre> , <p> , etc. must be
separated from surrounding content by blank lines, and the start and end tags of the block should not be indented
with tabs or spaces.
2. Doxygen doesn't translate the content within <code> and </code> , but eliminate the lead spaces of the code and make
the typesetting a mess. If you want to insert formatted code in comments or Markdown, use <pre>``</pre> tags or indent
the code with 4 spaces.
3. Doxygen only support a few common tags, it processes JavaScript code or other tags like button as pure text, and
escape all special JavaScript characters, therefore invalidate the inserted code.
To reach what we expect, we need to add JavaScript to avoid escape. Replace the code with this:
<script>
$(document).ready(function(e) {
$('p').each(function(index, element) {
var text = $(this).html();
text = text.replace('$BEGIN$','');
text = text.replace('$END$','');
text = text.replace('<','<');
text = text.replace('>','>');
$(this).html(text);
});
});
</script>
$BEGIN$
<button type="input" title="Test Button">Button</button>
$END$
Doxygen--Markdown Extensions
Tables
The seperator lines of the table consist of - and | , used to separate the columns and rows. The first line is called a
header line. Each table has only one header line, and each other line is a separate row, in which different items are
separated by | . The table above Will produce:
Will produce:
To make it look good, you can add | before the first and after the last column, and the output will stay the same:
Column alignment can be controlled via one or two colons at the header separator line:
Cautions
1: Doxygen only supports simple tables. If you want to use complex tables, do as follows:
Create and edit a table in word, transfer it into HTML code, and copy the code to Markdown article.
or other methods.
Besides using backtick quotes to insert code, common Markdown editors also provide extra commands to support inserting
a whole code block, and a common command is like this:
```
```
Differently, Doxygen supports code blocks by surrounding the code with a pair of "fence lines". Such a line consists of 3 or
more tilde ( ~ ) characters on a line. Here is an example:
Example 1
~~~
~~~
Note that the end of the block should have the same number of tildes. For example, the command below is wrong:
Meanwhile, you can also make the code block appear with syntax highlighting. For example:
~~~{.programming language}
~~~
Or
~~~programming language
~~~
Example 2
~~~{.c}
~~~
Header Id Attributes
Standard Markdown has no support for labeling headers, which is a problem if you want to link to a section.
Generally, we use HTML syntax to create an ID for the header, like this:
* [Overview](#overview)
* [Installation](#installation)
<h1 id="overview">Overview</h1>
<h2 id="install">Installation</h2>
But it isn't obedient to Markdown philosophy, so PHP Markdown Extra allows you to label a header by adding the following
to the header:
Overview {#overview}
========
## Installation ## {#installation}
Having the header ID, we can link the header to corresponding section in the artible, like this:
Example 1
* [Overview](#overview)
* [Installation](#installation)
Overview {#overview}
========
## Installation ## {#install}
Doxygen supports a special link marker [TOC] which can be placed in a page to produce a table of contents at the start of
the page, listing all sections. For details, please refer to next section.
Cautions
2. When using # , the header must be surrounded by the pound signs, e.g. the following command is wrong:
## Installation {#installation}
3. To link to a section in the same article or comment block you can use [Link text](#labelid) . To link to a section in
general, use # instead of @ like this:
[Link text](@labelid)
4. To put a Markdown article on the main page of the output file, please set the configuration of the first header in the
Markdown article as index or mainpage .
Table of Contents
Doxygen supports a special link marker [TOC] which can be placed in a page to produce a table of contents at the start of
the page, listing all sections. For example:
Example 1
* [Overview](#overview)
* [Installation](#installation)
Overview {#overview}
========
## Installation ## {#installation}
Will produce
Cautions
Overview {#Overview}
========
## Installation ## {#Installation}
[TOC]
1. Markdown headers must have ID attributes, otherwise Doxygen doesn't generate a catalog.
[TOC]
Overview
========
## Installation ##
To be specific:
Doxygen allows using a complete Markdown path (file name included) in a normal link to link to external Markdown file, like
this:
Note: If the file and the file to be linked are in the same directory, use the file name directly, like this:
By default, Doxygen uses the linked Markdown file name as the name shown in the document. Meanwhile, Doxygen allows
users to define the shown name of the file:
For example, if we want to call function SystemInit , we can write like this:
\ref SystemInit
Ending
That's all for how to use Markdown in Doxygen. There are a lot of traps, and special attention is needed to the cautions.
Many materials were referred to when writing this document. Many thanks! If you find any mistake or any paragraph hard to
understand, please let us know, we will fix it any soon as possible.
References
1. Doxygen Manual main page
2. Doxygen Manual main page--Markdown support
3. Markdown standard syntax--Chinese version
4. Markdown standard syntax--English version
5. Markdown standard syntax--Quickstart Chinese version
Windows platform
MarkdownPad
MarkPad
Linux platform
ReText
Mac platform
Mou
Online editors
stackedit.io
Markable.in
Dillinger.io
Browser plugin
MaDe (Chrome)
Advanced application
Sublime Text 2
MarkdownEditing
SublineMarkdown Manual
Compiler Setting
Before you use CoIDE to start your project, you need to configure the GCC compiler and debugger at first.
CooCox suggest you to choose ARM GCC as the compiler since it is from ARM official. If you want to know more details
about ARM GCC, please click here. In additional, you can also choose the other GCC compiler such as CodeSourcery
GCC.
Note:
As CoIDE support different GCC compiler, you need to pay attention to the following point when you switch between the
compilers:
The different compilers have different C libraries, for example: ARM GCC have a base C Library and Semihosting
Library, Retarget Library. However, Code Sourcery GCC only have the base C Library. See: Project Configuration
Different GCC tools use different link.ld when they compile the same project. When you click the Build button, CoIDE
will generate the link.ld file according to the project configuration before the build start.
If you want to compile the project that created under other GCC tools in CoIDE, you may need to select that tool as the
GCC toolchain, and don't forget to select the .ld files , you need to delete the Build.xml, link.ld, memory.ld. Then
check a component and reconfigure the project after setting the GCC.
After launching CooCox CoIDE, Click "Select Toolchain path" under the Project menu.
Click the browse button, select the folder which contains the arm-none-eabi-gcc.exe and the other gcc execute files.
After set the GCC Toolchain, you can use the CoIDE to create a project and try the other function. See: CoIDE QuickStart.
If you want to compile the project that created under other GCC tools in CoIDE, you may need to select that tool as the
GCC toolchain, and don't forget to select the .ld files , you need to delete the Build.xml, link.ld, memory.ld. Then
check a component and reconfigure the project after setting the GCC.