Updated some of the documentation

This commit is contained in:
Steve Karg
2020-06-19 07:48:06 -05:00
parent ff9697bab4
commit fbef685063
10 changed files with 127 additions and 221 deletions
+15 -3
View File
@@ -3,15 +3,27 @@ Build using Code Blocks
Q1: GNU GCC Compiler, undefined reference to closesocket
A1: Under Project->Build Options->Linker settings,
A1: Under Project->Build Options->Linker settings,
add "ws2_32" to Link Libraries.
Q2: GNU GCC Compiler, creating a DLL
A2: Under Project->Build Options->Linker settings,
A2: Under Project->Build Options->Linker settings,
add "user32" to Link Libraries.
Q3: GNU GCC Compiler, undefined reference to _GetAdaptersInfo
A3: Under Project->Build Options->Linker settings,
A3: Under Project->Build Options->Linker settings,
add "iphlpapi" to Link Libraries.
Q4: I don't see any Code::Blocks project files. How do I build?
A4: Use cmake to generate the project file. For example:
$ mkdir build && cd build
$ cmake -G"CodeBlocks - Unix Makefiles" ..
or any of the following generators depending on your compiler preference:
CodeBlocks - MinGW Makefiles
CodeBlocks - NMake Makefiles
CodeBlocks - NMake Makefiles JOM
CodeBlocks - Ninja
CodeBlocks - Unix Makefiles
+1
View File
@@ -5,3 +5,4 @@ Q1: Cannot open include file: 'winsock2.h'
A1: Install the Microsoft Platform SDK:
http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/default.aspx
+21 -19
View File
@@ -2,40 +2,42 @@ SourceForge Release Checklist for the BACnet Embedded Stack Project
written by Steve Karg (using a similar doc by Kim Gräsman as a guide)
Verify that the test build is clean. Test code with clean directory.
Get a clean build (no warnings or errors).
The program must be functional (it works).
Clean up the object files and binaries to prepare for tar
$ make clean
Make the source code look the same
$ ./indent.sh
$ ./comment.sh
$ ./fixup.sh
$ make pretty
$ make tidy
Verify that the code compiles and runs the demos without error or
warnings:
$ make all
$ demo/server 123 (etc)
$ make lint
$ make clean all
$ ./bin/server 123
Verify that the unit tests compile and pass:
$ ./unittest.sh
$ cat test.log | grep Failed
$ make test
Commit any changes to subversion.
$ svn commit
$ svn update
Note: The continuous integration of Travis, Github Workflow, and AppVeyor
run compilations and tests for the various platforms and compilers
supported by this library, and will flag an error if detected.
Run the release script:
$ ./release.sh 0.0.0
Commit any changes to a release branch, such as bacnet-stack-1.0 or
bacnet-stack-1.1 and tag as bacnet-stack-1.0.0 or bacnet-stack-1.0.1
Perform git repository management at github, and push the mirror to
git at sourceforge.net repository.
Go to file manager at http://sourceforge.net/projects/bacnet/
Admin -> File Manager
Tag the files for the various platforms
Tag the ChangeLog as release notes.
Update the website (if necessary)
Update the bacnet.sf.net website (if necessary)
Add release notes under What's New on SourceForge.
The release notes should include project details
for someone unfamiliar with the project or BACnet.
+21 -22
View File
@@ -1,36 +1,35 @@
SLOC Directory SLOC-by-Language (Sorted)
39094 ports ansic=35270,cpp=3339,xml=214,sh=154,asm=117
30563 demo ansic=30100,perl=463
23732 src_top_dir ansic=23732
5580 include ansic=5580
2189 nbproject xml=2137,sh=52
757 bin sh=757
428 top_dir sh=428
234 test ansic=234
37 lib cpp=37
SLOC Directory SLOC-by-Language (Sorted)
84560 ports ansic=70066,asm=9265,cpp=4651,xml=424,sh=154
72724 src_bacnet ansic=72724
15569 apps ansic=15011,perl=463,javascript=91,sh=4
721 test ansic=721
257 bin sh=257
5 top_dir sh=5
0 cmake (none)
0 doc (none)
0 license (none)
0 obj (none)
0 src_top_dir (none)
Totals grouped by language (dominant language first):
ansic: 94916 (92.50%)
cpp: 3376 (3.29%)
xml: 2351 (2.29%)
sh: 1391 (1.36%)
perl: 463 (0.45%)
asm: 117 (0.11%)
ansic: 158522 (91.19%)
asm: 9265 (5.33%)
cpp: 4651 (2.68%)
perl: 463 (0.27%)
xml: 424 (0.24%)
sh: 420 (0.24%)
javascript: 91 (0.05%)
Total Physical Source Lines of Code (SLOC) = 102,614
Development Effort Estimate, Person-Years (Person-Months) = 25.87 (310.44)
Total Physical Source Lines of Code (SLOC) = 173,836
Development Effort Estimate, Person-Years (Person-Months) = 45.00 (539.96)
(Basic COCOMO model, Person-Months = 2.4 * (KSLOC**1.05))
Schedule Estimate, Years (Months) = 1.84 (22.13)
Schedule Estimate, Years (Months) = 2.28 (27.30)
(Basic COCOMO model, Months = 2.5 * (person-months**0.38))
Estimated Average Number of Developers (Effort/Schedule) = 14.03
Total Estimated Cost to Develop = $ 3,494,689
Estimated Average Number of Developers (Effort/Schedule) = 19.78
Total Estimated Cost to Develop = $ 6,078,387
(average salary = $56,286/year, overhead = 2.40).
SLOCCount, Copyright (C) 2001-2004 David A. Wheeler
SLOCCount is Open Source Software/Free Software, licensed under the GNU GPL.
-138
View File
@@ -1,138 +0,0 @@
========== Using Subversion to get the BACnet Stack source code ==========
To check out the trunk from the subversion repository,
use "svn co", e.g.
svn checkout https://svn.code.sf.net/p/bacnet/code/trunk/bacnet-stack/
or for the stable releases:
svn checkout https://svn.code.sf.net/p/bacnet/code/tags/bacnet-stack-0-7-1/
for Anonymous checkout, use http vs. https.
========== Configure your Subversion Client for EOL properties ==========
Committers need to properly configure their svn client so that
the appropriate subversion properties are set on newly added files.
One of the most important properties is the eol-style property
that configures OS-specific line-endings for text files.
Add the configuration text below to your subversion client
configuration file that is normally in the following location:
Windows: %USERPROFILE%\Application Data\Subversion\config
or %appdata%\subversion\config
or Click the 'edit' button for 'Subversion configuration file' in
the TortoiseSVN settings dialog under General.
Linux: ~/.subversion/config or /etc/subversion/config
Warning: Make sure the settings are merged into the appropriate
section if it already exists, as duplicate section names can
cause problems.
[auto-props]
### The format of the entries is:
### file-name-pattern = propname[=value][;propname[=value]...]
### The file-name-pattern can contain wildcards (such as '*' and
### '?'). All entries which match will be applied to the file.
### Note that auto-props functionality must be enabled, which
### is typically done by setting the 'enable-auto-props' option.
*.c = svn:eol-style=native
*.cpp = svn:eol-style=native
*.h = svn:eol-style=native
*.dsp = svn:eol-style=CRLF
*.dsw = svn:eol-style=CRLF
*.sh = svn:executable;svn:eol-style=native
*.cmd = svn:mime-type=text/plain;svn:eol-style=CRLF
*.bat = svn:mime-type=text/plain;svn:eol-style=CRLF
Makefile = svn:eol-style=native
*.obj = svn:mime-type=application/octet-stream
*.bin = svn:mime-type=application/octet-stream
*.bmp = svn:mime-type=image/bmp
*.class = svn:mime-type=application/java
*.doc = svn:mime-type=application/msword
*.exe = svn:mime-type=application/octet-stream
*.gif = svn:mime-type=image/gif
*.gz = svn:mime-type=application/x-gzip
*.jar = svn:mime-type=application/java-archive
*.jelly = svn:mime-type=text/plain;svn:eol-style=native
*.jpg = svn:mime-type=image/jpeg
*.jpeg = svn:mime-type=image/jpeg
*.pdf = svn:mime-type=application/pdf
*.png = svn:mime-type=image/png
*.tgz = svn:mime-type=application/octet-stream
*.tif = svn:mime-type=image/tiff
*.tiff = svn:mime-type=image/tiff
*.zip = svn:mime-type=application/zip
*.txt = svn:mime-type=text/plain;svn:eol-style=native
*.xml = svn:mime-type=text/xml;svn:eol-style=native
*.ent = svn:mime-type=text/plain;svn:eol-style=native
*.dtd = svn:mime-type=text/plain;svn:eol-style=native
*.vsl = svn:mime-type=text/plain;svn:eol-style=native
*.xsd = svn:mime-type=text/xml;svn:eol-style=native
*.xsl = svn:mime-type=text/xml;svn:eol-style=native
*.wsdl = svn:mime-type=text/xml;svn:eol-style=native
*.htm = svn:mime-type=text/html;svn:eol-style=native
*.html = svn:mime-type=text/html;svn:eol-style=native
*.css = svn:mime-type=text/css;svn:eol-style=native
*.js = svn:mime-type=text/plain;svn:eol-style=native
*.jsp = svn:mime-type=text/plain;svn:eol-style=native
*.txt = svn:mime-type=text/plain;svn:eol-style=native
*.java = svn:mime-type=text/plain;svn:eol-style=native
*.properties = svn:mime-type=text/plain;svn:eol-style=native
*.sql = svn:mime-type=text/plain;svn:eol-style=native
*.sln = svn:eol-style=CRLF
*.vcproj = svn:eol-style=CRLF
To test the properties of a file:
$ svn proplist
If a file slips into subversion without the eol-style property set,
you can periodically run:
$ svn propset svn:eol-style native *
$ svn commit -m "changed eol-style"
========== BACnet Stack source code management workflow ==========
From http://stackoverflow.com/questions/16142/what-do-branch-tag-and-trunk-really-mean
Paraphrased and copied from gregmac:
We are working on what will be 1.0.0 in trunk. Once 1.0.0 is finished,
branch trunk into a new "bacnet-stack-1.0.0" branch,
and create a "1.0.0" tag. Work on what will eventually be 1.1.0 continues
in trunk.
When you come across some bugs in the code, fix them in the trunk.
Then merge the fixes over to the 1.0.0 branch. You may also get bug
reports for 1.0.0, and fix the bugs in the 1.0.0 branch, and then merge
them back to trunk. Sometimes a bug can only be fixed in 1.0.0 because
it is obsolete in 1.1.0. It doesn't really matter, the only thing is
you want to make sure that you don't release 1.1.0 with the same bugs
that have been fixed in 1.0.0. Once you find enough bugs
(or maybe one critical bug), you decide to do a 1.0.1 release.
So you make a tag "1.0.1" from the 1.0.0 branch, and release the code.
At this point, trunk sill contains what will be 1.1.0, and
the "1.0.0" branch contains 1.0.1 code. The next time you release an
update to 1.0.0, it would be 1.0.2.
Eventually you are almost ready to release 1.1.0, but you want to do
a beta first. In this case, you likely do a "1.1.0" branch, and
a "1.1beta1" tag. Now, work on what will be 1.2.0 (or 2.0.0 maybe)
continues in trunk, but work on 1.1.0 continues in the "1.1.0" branch.
Once you release 1.1.0 final, you do a "1.1.0" tag from the "1.1.0" branch.
You can also continue to maintain 1.0.0 if you'd like, porting bug fixes
between all 3 branches (1.0.0, 1.1.0, and trunk). The important take
away is that for every main version of the software you are maintaining,
you have a branch that contains the latest version of code for that version.
Another use of branches is for features. This is where you branch trunk
(or one of your release branches) and work on a new feature in isolation.
Once the feature is completed, you merge it back in and remove the branch.
The idea of this is when you're working on something disruptive
(that would hold up or interfere with other people from doing their work),
something experimental (that may not even make it in), or possibly just
something that takes a long time (and you're afraid if it holding up a
1.2.0 release when you're ready to branch 1.2.0 from trunk), you can do
it in isolation in branch. Generally you keep it up to date with trunk by
merging changes into it all the time, which makes it easier to re-integrate
(merge back to trunk) when you're finished.
+17 -21
View File
@@ -1,33 +1,29 @@
To Do List - BACnet Stack at SourceForge
Here are some things to do:
A. Finish demo/epics/main.c - EPICS demo. Use object property lists.
B. Update demo/object/lo.c - Lighting Output object demo - match addendum
C. Add storage hooks to bvlc.c for BDT and FDT.
D. Merge blvc.c network variable storage (ntohl, htonl) to bip.c.
A. Finish apps/epics/main.c - EPICS demo. Use object property lists.
B. Update src/bacnet/basic/object/lo.c - Lighting Output object demo
C.
D.
E. Add HTTP demo like bacnet4linux
F. Add SubscribeCOVProperty support in server demo.
G. Add hooks to increment Database_Revision property
H. Change demo objects and WhoHas to use CharacterString for Object_Name.
H.
I. Change core encode/decode to pass length for safe handling
J. Change bip.c to not use extra buffer (shift data)
K. Add Visual Studio makefiles, projects, or solutions for demos.
L. Add Code::Blocks projects for demos.
J.
K.
L.
M. Add function headers to each module and function with
doc-tags for document generator doxygen (in progress).
N. Add option to address module that use file store address cache
instead of having to send who-is for each query.
This will make scripting cleaner/effecient.
O. Convert object methods to use an array of object methods
for ReadProperty and Device object counts, ids, and names.
P. Convert datalink methods to use function pointers that can be
overridden in main.c.
Q. Create BACnet router code that uses more than one datalink.
R. splint more of the code. Make intelligent fixes.
S. Fix src/mstp.c so that indent can parse it correctly.
T. Add "inline" to static functions that are only used once.
U. Modify code to compile with MISRA C rules.
V. Change OBJECT_ID to only be 32 bits, and add macro handlers.
N.
O.
P. Convert datalink methods to use network port objects
Q.
R.
S.
T.
U.
V.
W. Add #ifdef for all MAX_ defines so they can be overridden.
X. Change WhoIs demo to list all I-Am's received such that duplicate
IDs with different MAC addresses can be detected.
+4 -7
View File
@@ -1,17 +1,14 @@
Add the ability to compile, edit, and maintain code
Here are the compilers and their documents
$ sudo apt-get install build-essential subversion-tools gcc-4.2-doc glibc-doc manpages-dev
$ sudo apt-get install build-essential git cmake
$ sudo apt-get install mingw32 mingw32-binutils mingw32-runtime
I need access to subversion and XSLT ChangeLog tools
$ sudo apt-get install subversion-tools
$ sudo apt-get install xsltproc
I install a couple of editors, useful for various things. Kate is already installed.
I install a couple of editors, useful for various things.
$ sudo apt-get install scite
$ sudo apt-get install vim-full
Useful tools for cleaning up code, converting comments and line endings, and code statistics:
$ sudo apt-get install splint
$ sudo apt-get install clang-tools
$ sudo apt-get install clang-format
$ sudo apt-get install sloccount
$ sudo apt-get install indent
$ sudo apt-get install liwc
$ sudo apt-get install tofrodos
+35
View File
@@ -0,0 +1,35 @@
========== BACnet Stack source code management workflow ==========
We are working on what will be 1.0.0 in . Once 1.0.0 is finished,
branch master into a new "bacnet-stack-1.0" branch,
and create a "1.0.0" tag. Work on what will eventually be 1.1.0 continues
in master.
When you come across some bugs in the code, fix them in master.
Then merge the fixes over to the 1.0 branch. You may also get bug
reports for 1.0.0, and fix the bugs in the 1.0 branch, and then merge
them back to master. Sometimes a bug can only be fixed in 1.0 because
it is obsolete in 1.1. It doesn't really matter, the only thing is
you want to make sure that you don't release 1.1.0 with the same bugs
that have been fixed in 1.0 branch. Once you find enough bugs
(or maybe one critical bug), you decide to do a 1.0.1 release.
So you make a tag "1.0.1" from the 1.0 branch, and release the code.
At this point, master sill contains what will be 1.1.0, and
the "1.0.0" branch contains 1.0.1 code. The next time you release an
update to 1.0 branch, it would be 1.0.2.
You can also continue to maintain 1.0 brance if you'd like, porting bug fixes
between all 3 branches (1.0.0, 1.1.0, and master). The important take
away is that for every main version of the software you are maintaining,
you have a branch that contains the latest version of code for that version.
Another use of branches is for features. This is where you branch master
(or one of your release branches) and work on a new feature in isolation.
Once the feature is completed, you merge it back in and remove the branch.
The idea of this is when you're working on something disruptive
(that would hold up or interfere with other people from doing their work),
something experimental (that may not even make it in), or possibly just
something that takes a long time (and you're afraid if it holding up a
1.2.0 release when you're ready to branch 1.2.0 from master), you can do
it in isolation in branch. Generally you keep it up to date with master by
merging changes into it all the time, which makes it easier to re-integrate
(merge back to master) when you're finished.
+4 -2
View File
@@ -3,11 +3,11 @@ different compilers; here are some rules for writing code that will work
on multiple platforms.
Regarding tabs, indenting, and code style, we run:
$ indent -kr -nut -nlp -ip4 -cli4 -bfda -nbc -nbbo -c0 -cd0 -cp0 -di0 -l79 filename.c
$ clang-format -i -style=file -fallback-style=none filename.c
on the code prior to releasing it. This ensures a standard look and feel
to the code regardless of the authors preferred style. You may certainly
adjust the code to your preferred style using an indent tool. We use the
script indent.sh to adjust all the .c and .h files.
"make pretty" to adjust all the .c and .h files.
For variable names, separate words within the variables by underscores.
Do not use capital letters as separators. Consider how much harder
@@ -233,3 +233,5 @@ header file, and the dependent routine is placed in a ports directory.
Reference: The cross platform aspect of this coding standard is based
on the developer coding standard for Ethereal/Wireshark and has been
modified by Steve Karg for this project. Thank you, Ethereal/Wireshark!
The naming convention is based on the writings of Jack Ganssle. Thank you,
Jack!
+9 -9
View File
@@ -1,9 +1,9 @@
# How to configure clangformat
# How to configure clang-format
## Overview
clang-format is an utility to format source code in several languages
according to predefined settings. Settings for auto-formatting of C source
files are summarized below, and should be saved in .clang-format file in root
clang-format is an utility to format source code in several languages
according to predefined settings. Settings for auto-formatting of C source
files are summarized below, and should be saved in .clang-format file in root
folder. These settings are chosen to closely match the formatting style used.
## Configuring Editors
@@ -22,16 +22,16 @@ Add the line
to `~/.emacs.d/init.el`. Format a source file with `M-x clang-format-region`.
### CLion
* Add the .clang-format file to the root directory as
explained above. Go to File->Settings->Tools->External Tools
and click on the plus sign. A window should pop up.
* Add the .clang-format file to the root directory as
explained above. Go to File->Settings->Tools->External Tools
and click on the plus sign. A window should pop up.
Choose a name, for example "clang-format"
* For the Tool settings tab use this configuration:
- Program: `clang-format` (use the name of your executable here)
- Parameters: `--style=file -i $FileName$`
- Working directory: `$FileDir$`
With your file open, go to `Tools->External tools` and run the config above.
This calls `clang-format` and does in-place formatting using the style
With your file open, go to `Tools->External tools` and run the config above.
This calls `clang-format` and does in-place formatting using the style
defined in the first `.clang-format` file found in a parent directory.
### .clang-format file