README.md 5.63 KB
Newer Older
1
2
# MBsysC: Contribution files, all you need to know before developing MBsysC
  
3
4
5
6
7
8
9
10
This folder contains all the information about MBsysC organisation, coding convention, templates, ...
MbsysC is the C implementation for [Robotran](http://www.robotran.be/)

# Coding convention

## Naming convention
 Two naming rules are used in MBsysC, the _CamelCase_ rule and the _lower_case_with_underscores_:
 * __Structures__ follow the _CamelCase_ rule: `struct MbsData`
11
 * __Variables__ (including arguments) follow the _lower_case_with_underscores_ rule: `MbsData *mbs_data;` or `mbs_data->mbs_filename; `
12
13
14
15
16
17
18
19
20
21
22
23
24
25
 * __Functions__ follow the _lower_case_with_underscores_ rule: `MbsDirdyn* mbs_new_dirdyn(MbsData* mbs_data);`

## Statements
 * Avoid single-line statement;
 * Always use braces;
 * Opening braces have to be on the statement line;
 * Closing brace should be alone, aligned with the statement;
 * An identation (4 spaces, see later) is mandatory.

__A good example:__

```c
    if(i<1){
        /* do stuffs */
26
    }
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
```

This is tolerated, but not recommended:

```c
    if(i<1) {/* do one-line instruction */}
        
```

All the following should be banned:

```c
    if(i<1)
        /* do one-line instruction */
```
```c
    if(i<1) /* do one-line instruction */
```

```c
    if(i<1){
    /* do stuffs */
    /* do other stuffs */}
```

## IDEs and editors configuration
 * __Identation__ are __4 spaces__ characters not tabular (`\t`);
 * __Remove white spaces__ from end of line;
 * __File encoding__ is __UTF8__;
 * __End of line__ (EOL) is __LF__ (`\n`);
 * __Files end__ by one newline.

## Documentation
60
The documentation is provided online and synchronized with the _dev_ branch: [MbsysC Doc](http://robotran.git-page.immc.ucl.ac.be/mbsysc/).
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
General rules:
 * All function should be documented (purpose, arguments, return values)
 * The documentation is written in the header files.

Here is an example __for a function__:
```C
/*! \brief remove an old index in a q vector
 *
 * It does not modify the vector and vector size if the index is not in the q vector.
 *
 * \param[in,out] q_vec original q vector, have to be initialized at size njoint
 * \param[in] nq number of elements in the original vector
 * \param[in] old_q old index to remove
 * 
 * \return the number of elements in the updated vector
 */
int remove_mbs_q_elem(int *q_vec, int nq, int old_q);
```
 * `\brief` is followed by one-line, short description. After a blank line full description can be given.
 * `\param` (or `\p`) is followed by:
     * `[in]` if the argument is only read by the function;
     * `[out]` if the argument is only modified by the function;
     * `[in,out]` if the argument is read and modified by the function;
     * The argument name and then the description its description.
 * `\return` is followed by the description of the returned values.

Another example, for a structure:
```
/*!
 * Structure containing the definition of the Multibody System.
 */
struct MbsData
{
94
95
96
97
98
99
100
101
102
103
104
    int npt; //! Number of anchor points.
    double *dpt[3+1]; //! Array containing the coordinate of all anchor points.
    int *qlocked; //! Array with the indices of locked articulations.
                  //! Those articulations have a constant position defined by the user \f$ q(nqc)=cte \f$.
    double **SWr;//! Array of Swr vector for each external forces.
                 //! Swr(9,1) = [Fx; Fy; Fz; Mx; My; Mz; dxF]:
                 //! - Force components (expressed in the inertial frame) : Fx, Fy, Fz
                 //! - Pure torque components (expressed in the inertial frame) : Mx, My, Mz
                 //! - Application point local coordinates vector (expressed in the body-fixed frame): dxF(1:3,1)
                 //!
                 //! WARNING: Indexes convention is the opposite of what is usually done in MBsysC.
105
106
107
108
};
```
Nothing special, but note:
 * LaTeX equations are supported: `\f$ q(nqc)=cte \f$` ;
109
 * First line appear on the summary of the member, other line in the detailed part of the documentation;
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
 * Lists are supported.


# Error handling
All you need to know about error management in MBsysC is in the wiki [error code](https://git.immc.ucl.ac.be/robotran/mbsysc/wikis/error-code)

# MBsysC filetree structure

```bash
.
├──Contribute
├──ExampleProjects
├──MBsysC
│  ├── cmake_aux : Various CMake stuffs
│  ├── conf : CMake specific file to find libraries
│  ├── mbs_app : Source file for stand alone application related to MBsysC
│  ├── mbs_common : Source files
│  │   ├── mbs_add_on
│  │   ├── mbs_load_xml
│  │   ├── mbs_module
│  │   ├── mbs_numerics
│  │   │   └── mbs_integrators
│  │   ├── mbs_realtime
│  │   ├── mbs_struct
│  │   ├── mbs_utilities
│  │   └── mbs_void_symbolicR
│  ├── mbs_documentation
│  ├── mbs_interface : Source code for interfacing with other languages
│  ├── mbs_workspace_template : Templates for Robotran project with MBsysC
│  ├── mbsyspad
│  ├── mbsyspad_mac_os
│  ├── opengl_mbs
│  ├── readme_aux
│  ├── tests : Instruction for CI test
│  └── win64_include_lib: External compiled libraries
```

# Gitlab 
 * Automatic tests (Tutorials  and specifics projetcs) runs online when pushing to gitlab:
     * Some tests are only done in the _dev_ branch;
     * The documentation is build when committing on the _dev_ branch;
     * Avoid test running by putting `[Ci-skip]` anywhere in the commit message (with brackets);
 * Never merge your own merge request, ask a colleague.
 * Never commit in the _dev_ and _master_ branches.