diff --git a/doc/README.codeblocks b/doc/README.codeblocks index ca37e963..14710e6e 100644 --- a/doc/README.codeblocks +++ b/doc/README.codeblocks @@ -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 diff --git a/doc/README.msvs b/doc/README.msvs index 4a34905e..d8a037c5 100644 --- a/doc/README.msvs +++ b/doc/README.msvs @@ -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 + diff --git a/doc/README.release b/doc/README.release index 6e04b534..4ab4dab8 100644 --- a/doc/README.release +++ b/doc/README.release @@ -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. diff --git a/doc/README.sloc b/doc/README.sloc index 60b0c961..fc991858 100644 --- a/doc/README.sloc +++ b/doc/README.sloc @@ -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. diff --git a/doc/README.subversion b/doc/README.subversion deleted file mode 100644 index 081ac819..00000000 --- a/doc/README.subversion +++ /dev/null @@ -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. diff --git a/doc/README.todo b/doc/README.todo index 276b61fb..d32a445c 100644 --- a/doc/README.todo +++ b/doc/README.todo @@ -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. diff --git a/doc/README.ubuntu b/doc/README.ubuntu index ff7e6286..42708fe0 100644 --- a/doc/README.ubuntu +++ b/doc/README.ubuntu @@ -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 \ No newline at end of file diff --git a/doc/README.workflow b/doc/README.workflow new file mode 100644 index 00000000..2a4b5fa2 --- /dev/null +++ b/doc/README.workflow @@ -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. diff --git a/doc/code-standard.txt b/doc/code-standard.txt index 12548865..af4a23ef 100644 --- a/doc/code-standard.txt +++ b/doc/code-standard.txt @@ -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! diff --git a/doc/indent/README.md b/doc/indent/README.md index 9e37132e..3f39ada8 100644 --- a/doc/indent/README.md +++ b/doc/indent/README.md @@ -1,9 +1,9 @@ -# How to configure clangâ€format +# 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