Install (developer documentation) file for the sm_calculator (SM Calculator) solution. ---------------------------------------- In this document Developer can find necessary info about structure of this solution (sm_calculator - SM Calculator), necessary tools and how this solution can be built and tested. Downloading the SM Calculator source files: -------------------- Source files of the sm_calculator (SM Calculator) solution can de found here: http://smansoft.com/sm_calculator/ Also, developer can find source files here: https://github.com/smansoft/sm_calculator . Developer can use command git clone https://github.com/smansoft/sm_calculator.git to get sources from github repository. The basic directory layout of SM Calculator solution is as follows: -------------------- / _cmake/ - directory, that contains scripts for build of all suite of projects (solution) (subdir "_build" is created during build); cmake_build.nmake.bat - script, that provides build of the project, using cmake, "NMake Makefiles" generator and nmake build of Visual Studio 2019 (Windows); during build, directory "_build" is created; cmake_build.vs.x64.bat - script, that generates solution and suite of projects (using cmake, "Visual Studio 16 2019" generator, x64 platform) for follow build, using Visual Studio 2019 (Windows); solution and suite of projects is created in subdirectory "_build"; cmake_build.vs.x86.bat - script, that generates solution and suite of projects (using cmake, "Visual Studio 16 2019" generator, Win32 platform) for follow build, using Visual Studio 2019 (Windows); solution and suite of projects is created in subdirectory "_build"; cmake_build.sh - script, that provides build of the project, using cmake, "Unix Makefiles" generator and make/gcc build (GCC, Linux platform); during build, directory "_build" is created; cmake_clear.bat - clear result of build (Windows); cmake_clear.sh - clear result of build (Linux); deps/ - directory, that contains dependency projects (cmocka_lib, getopt_lib, sstring_lib); cmocka_lib/ - C-based testing framework/library (dynamic and static modules/libraries are created during build); getopt_lib/ - getopt library (parsing and processing of command line options); sstring_lib/ - secure string and safe memory control library (instead C run-time functions); log_lib/ - simple logging library (supports synchronizing); sm_calc/ - main project (sm_calc) of the solution: SM Calculator; CMakeLists.txt - txt file, that is used by cmake (tool, that provides managing the build process) for generation of projects; - header files of the project; pch.h framework.h sm_calc_types.h sm_calc_proc.h - header file, that contain definitions of all processing functions (which are used by syntax parser); sm_calc.h - files of the project which contain implementing code; sm_calc.c sm_calc_proc.c - file, that contain implementing of all processing functions (which are used by syntax parser); pch.c sm_calc.manifest - manifest file (used by Visual Studio 2019); sm_calc.l - specification of lexical analyzer; sm_calc_l.c - lexical analyzer generated by FLEX tool (generated from sm_calc.l); sm_calc.y - specification of syntax parser; sm_calc_y.output - report of generation of syntax parser by BISON tool; sm_calc_y.h - header file of syntax parser, generated by BISON tool (generated from sm_calc.y); sm_calc_y.c - definitions/implementing file of syntax parser, generated by BISON tool (generated from sm_calc.y); - project files of main module (sm_calc), which are used by Visual Studio 2019; sm_calc.vcxproj sm_calc.vcxproj.user sm_calc.vcxproj.filters sm_calc_tests/ - utility project, that is used for launching of unit tests in Visual Studio 2019 IDE; tests/ - suite of projects, which contains unit tests; CMakeLists.txt - txt file, that is used by cmake (tool, that provides managing the build process) for generation of projects; CTestTestfile.cmake - txt file, that contains declaration of unit tests (is used by sm_calc_tests utility project); - header files of unit testing projects; framework.h pch.h - files of unit testing projects which contain implementing code; pch.c sm_calc_test.c - module, that contains basic unit test, which provides testing of functionality, declared and implemented in files sm_calc_proc.h and sm_calc_proc.c; sm_calc_test_expr.c - unit test, that provides testing of functionality via call of main module function (from sm_calc.c), using option: --expression= sm_calc_test_files.c - unit test, that provides testing of functionality via call of main module function (from sm_calc.c), using options: --in_file= --out_file= - files, which contain suite of expressions, which are tested by sm_calc_test_files unit test application: sm_calc_test.in.01.txt sm_calc_test.in.02.txt sm_calc_test.in.03.txt sm_calc_test.in.04.txt sm_calc_test.in.05.txt sm_calc_test.in.06.txt sm_calc_test.in.07.txt - files, which contain execution results of sm_calc_test_files and processing of sm_calc_test.in.xx.txt: sm_calc_test.out.01.txt sm_calc_test.out.02.txt sm_calc_test.out.03.txt sm_calc_test.out.04.txt sm_calc_test.out.05.txt sm_calc_test.out.06.txt sm_calc_test.out.07.txt - temporary file, that contains execution result of sm_calc_test_expr: sm_calc_test.out.expr.txt - files, which contain true/correct execution results of sm_calc_test_files and processing of sm_calc_test.in.xx.txt; these files should be compared: sm_calc_test.check.xx.txt <--> sm_calc_test.out.xx.txt: sm_calc_test.check.01.txt sm_calc_test.check.02.txt sm_calc_test.check.03.txt sm_calc_test.check.04.txt sm_calc_test.check.05.txt sm_calc_test.check.06.txt sm_calc_test.check.07.txt - files, which should/can be used for comparing execution results of sm_calc_test_files and true/correct execution results of sm_calc_test_files (sm_calc_test.check.xx.txt <--> sm_calc_test.out.xx.txt): sm_calc_test_files.check.bat - batch (for Windows platform) script file, that compares files (sm_calc_test.check.xx.txt <--> sm_calc_test.out.xx.txt), using DIFF tool; sm_calc_test_files.check.sh - bash (for Linux platform) script file, that compares files (sm_calc_test.check.xx.txt <--> sm_calc_test.out.xx.txt), using DIFF tool; sm_calc_test_files.check.py - python 3 (multi-platform) script file, that compares files (sm_calc_test.check.xx.txt <--> sm_calc_test.out.xx.txt) (don't need any comparing tools); - project files of sm_calc_test module, which are used by Visual Studio 2019; sm_calc_test.vcxproj sm_calc_test.vcxproj.user sm_calc_test.vcxproj.filters - project files of sm_calc_test_expr module, which are used by Visual Studio 2019; sm_calc_test_expr.vcxproj sm_calc_test_expr.vcxproj.user sm_calc_test_expr.vcxproj.filters - project files of sm_calc_test_files module, which are used by Visual Studio 2019; sm_calc_test_files.vcxproj sm_calc_test_files.vcxproj.user sm_calc_test_files.vcxproj.filters CMakeLists.txt - txt file, that is used by cmake (tool, that provides managing the build process) for generation of projects; root cmake script; README - user manual of the application; HELP - short reference; INSTALL - developer manual of the project (this document); LICENSE - License file of the project and application (MIT License); sm_calc.fl_bis.bat - batch (for Windows platform) script file, that provides processing sm_calc.l and sm_calc.y specifications and generation files sm_calc_l.c, sm_calc_y.h, sm_calc_y.c using FLEX and BISON tools. As a rule this scripts is not needed to use, as processing of sm_calc.l and sm_calc.y specifications is provided during the build of sm_calc project; sm_calc.fl_bis.sh - bash (for Linux platform) script file, that provides processing sm_calc.l and sm_calc.y specifications and generation files sm_calc_l.c, sm_calc_y.h, sm_calc_y.c using FLEX and BISON tools. As a rule this scripts is not needed to use, as processing of sm_calc.l and sm_calc.y specifications is provided during the build of sm_calc project; sm_calculator.sln - solution file, that contains all subprojects (sm_calc, log_lib, sm_calc_test, ...), which are used by Visual Studio 2019; Projects of the solution : -------------------- sm_calc (sm_calc/) - main project of the solution; this project is built in this solution as executable module; log_lib (log_lib/) - small logging library (with synchronizing support); this library is built in this solution as static module/library; sstring_lib (deps/sstring_lib/) - secure string and safe memory control library (instead C run-time functions); this project is based on safestringlib; original sources can be found here: http://smansoft.com/sm_calculator/0.0.1.1/safestringlib/ http://smansoft.com/sm_calculator/0.0.1.1/safestringlib/safestringlib.zip http://smansoft.com/sm_calculator/0.0.1.1/safestringlib/safestringlib.tar.gz also developer can find these sources here: https://github.com/intel/safestringlib/ git clone https://github.com/intel/safestringlib.git original safestringlib project is published under MIT License; sstring_lib basicly contains functionality imported from original safestringlib, some small changes have been provided and several functions have been added; this library is built in this solution as static module/library; getopt_lib (deps/getopt_lib/) - getopt library (parsing and processing of command line options); this project is based on getoptlib; original sources can be found here: http://smansoft.com/sm_calculator/0.0.1.1/getopt/ http://smansoft.com/sm_calculator/0.0.1.1/getopt/getopt_mb_uni_src.zip also developer can find these sources here: https://www.codeproject.com/articles/157001/full-getopt-port-for-unicode-and-multibyte-microso original getoptlib project is published under LGPLv3 License; getopt_lib basicly contains functionality imported from original getoptlib, some small changes have been provided: support of build on Linux platform has been added; this library is built in this solution as shared module/library (according to original LGPLv3 License); cmocka_lib (deps/cmocka_lib/) - C-based testing framework/library (dynamic and static modules/libraries are created during build); this project is based on cmocka; original sources can be found here: http://smansoft.com/sm_calculator/0.0.1.1/cmocka/ http://smansoft.com/sm_calculator/0.0.1.1/cmocka/cmocka-1.1.5.tar.xz also developer can find these sources here: https://cmocka.org/files/1.1/ https://cmocka.org/files/1.1/cmocka-1.1.5.tar.xz original cmocka project is published under Apache License; cmocka_lib basicly contains functionality imported from original cmocka, some small changes have been provided: only build scripts have been changed and _cmake directory containing build scripts has been added; this library is built in this solution as static as dynamic modules/libraries; sm_calc_tests (sm_calc_tests/) - utility project, that is used for launching of unit tests in Visual Studio 2019 IDE; sm_calc_test (tests/) - unit test project, which provides testing of functionality, declared and implemented in files sm_calc/sm_calc_proc.h and sm_calc/sm_calc_proc.c; this project is built in this solution as executable module; sm_calc_test_expr (tests/) - unit test project, that provides testing of functionality via call of main module function (from sm_calc/m_calc.c), using option: --expression=; this project is built in this solution as executable module; sm_calc_test_files (tests/) - unit test, that provides testing of functionality via call of main module function (from sm_calc/m_calc.c), using options: --in_file= --out_file=; this project is built in this solution as executable module; Tools necessary for build of the project: -------------------- - Windows platform: - Visual Studio 2019 (including NMake tool); - CMake; developer can find CMAKE tool here: https://cmake.org/ https://cmake.org/download/ - flex; - bison; developer can find FLEX and BISON tools here: http://smansoft.com/sm_calculator/0.0.1.1/win_flex_bison/ http://smansoft.com/sm_calculator/0.0.1.1/win_flex_bison/win_flex_bison-2.5.22.zip or here: https://sourceforge.net/projects/winflexbison/ https://sourceforge.net/projects/winflexbison/files/ - diff (optionally); diff is a part of cygwin: https://www.cygwin.com/ or git: https://gitforwindows.org/ - Python 3 (optionally); developer can find Python 3 tool here: https://www.activestate.com/products/python/ - Linux platform: - GCC; - Make tool; - CMake; - flex; - bison; - bash; - diff (optionally); - Python 3 (optionally); The solution assembly has been tested at follow Linux distributions: Debian 10 (x64/x32); Debian 9 (x64/x32); openSUSE 15.1 (x64); Ubuntu 20.04 LTS (x64); Mint 19.3 (x64); The solution assembly: -------------------- -------------------- Windows platform: -------------------- There are follow ways for building of the project: - using /sm_calculator.sln and Visual Studio 2019 IDE; - using /_cmake/cmake_build.nmake.bat; - using /_cmake/cmake_build.vs.x64.bat or /_cmake/cmake_build.vs.x86.bat and then build, generated solution/projects using Visual Studio 2019 IDE; Developer can tune file /CMakeLists.txt before build: set (FLEX_CMD "win_flex.exe") set (FLEX_CMD_OPTIONS "-i -L --nounistd") set (BISON_CMD "win_bison.exe") set (BISON_CMD_OPTIONS "-l -d -v"). Developer can change path to win_flex, win_bison and change options before build, if it's necessary. -------------------- - using /sm_calculator.sln and Visual Studio 2019 IDE: This is the simplest way of build and can be used only for debug of the project. Built files will be generated in follow directories: /x64/bin.Debug /x64/bin.Release /Win32/bin.Debug /Win32/bin.Release , according to selected Solution Configuration and selected Solution Platform. Developer should start Build of the project sm_calc_tests for separate launching of all Unit Tests. If developer launches built sm_calculator(sm_calc.exe) in: /x64/bin.Debug /x64/bin.Release /Win32/bin.Debug /Win32/bin.Release , he should create subdirectories tree: /share/smansoft/doc/ in: /x64 /Win32 and copy there (in /x64/share/smansoft/doc/ or /Win32/share/smansoft/doc/) files: /README /HELP /LICENSE . In this case developer can run command help[;] in interactive mode. -------------------- - using /_cmake/cmake_build.nmake.bat: 1. Developer should launch "x64 Native Tools Command Prompt for VS 2019" or "x86 Native Tools Command Prompt for VS 2019" . 2. Then developer should call: cd <...sm_calculator/_cmake> , i.e. /_cmake directory should be current. 4. Developer can edit script: cmake_build.nmake.bat It's possible to use set BUILD_TYPE="Debug" or set BUILD_TYPE="Release" . 3. Developer should call cmake_build.nmake.bat 4. After that .bat script creates subdirectory: /_cmake/_build/, CMake generates here Makefile (/_cmake/_build/Makefile) and suite additional configuration files. Then .bat script launches: nmake clean - cleaning of previous build; nmake - build of the solution; nmake test - launching of unit tests; cpack -G "ZIP" %BUILD_TYPE% - creating the binary archive package /_cmake/_build/sm_calculator-0.0.1.1-Windows-x64.zip or /_cmake/_build/sm_calculator-0.0.1.1-Windows-x86.zip; cpack -G "ZIP" --config CPackSourceConfig.cmake - creating of sources archive package /_cmake/_build/sm_calculator-0.0.1.1-Source.zip; Developer can get as a result of this build: /_cmake/_build/sm_calculator-0.0.1.1-Windows-x64.zip - x64 binary archive package or /_cmake/_build/sm_calculator-0.0.1.1-Windows-x86.zip - x86 binary archive package and /_cmake/_build/sm_calculator-0.0.1.1-Source.zip - sources archive package. -------------------- - using /_cmake/cmake_build.vs.x64.bat or /_cmake/cmake_build.vs.x86.bat and then build, generated solution/projects using Visual Studio 2019 IDE: 1. Developer should call (in some command prompt): cd <...sm_calculator/_cmake> , i.e. /_cmake directory should ba current. 2. Launch script: cmake_build.vs.x64.bat or cmake_build.vs.x86.bat. 3. After that .bat script creates subdirectory: /_cmake/_build/ and CMake generates here solution and suite of projects. 4. Developer should launch Visual Studio 2019 IDE and open solution: /_cmake/_build/sm_calculator.sln 5. Solution sm_calculator.sln contains suite of projects, including: ALL_BUILD - full build of solution; RUN_TESTS - launching of all unit tests; INSTALL - creating the directory /_cmake/_build/sm_calculator-0.0.1.1-Windows-x64 or /_cmake/_build/sm_calculator-0.0.1.1-Windows-x86 and deployment of all installed files here; PACKAGE - creating the binary archive package /_cmake/_build/sm_calculator-0.0.1.1-Windows-x64.zip or /_cmake/_build/sm_calculator-0.0.1.1-Windows-x86.zip ; Developer can get as a result of this build: /_cmake/_build/sm_calculator-0.0.1.1-Windows-x64.zip - x64 binary archive package or /_cmake/_build/sm_calculator-0.0.1.1-Windows-x86.zip - x86 binary archive package. -------------------- Linux platform: -------------------- There is one way for building of the project: - using /_cmake/cmake_build.sh; -------------------- - using /_cmake/cmake_build.sh: 1. Developer should call: cd <...sm_calculator/_cmake> , i.e. /_cmake directory should be current. 2. Developer can edit script: cmake_build.nmake.bat It's possible to use BUILD_TYPE="Debug" or BUILD_TYPE="Release" . Also developer can edit: export CXX="gcc"; It depends on gcc version, that should be used (in some Linux distributions); 3. Developer should call cmake_build.sh; 4. After that .sh script creates subdirectory: /_cmake/_build/, CMake generates here Makefile (/_cmake/_build/Makefile) and suite additional configuration files. Then .sh script launches: make - cleaning of previous build; make all test; - build of the solution and launching of unit tests; cpack -G "TGZ"; - creating the binary archive package /_cmake/_build/sm_calculator-0.0.1.1-Linux-x64.tar.gz or /_cmake/_build/sm_calculator-0.0.1.1-Linux-x86.tar.gz cpack -G "TGZ" --config CPackSourceConfig.cmake; - creating of sources archive package /_cmake/_build/sm_calculator-0.0.1.1-Source.tar.gz; Developer can get as a result of this build: /_cmake/_build/sm_calculator-0.0.1.1-Linux-x64.tar.gz - x64 binary archive package or /_cmake/_build/sm_calculator-0.0.1.1-Linux-x86.tar.gz - x86 binary archive package and /_cmake/_build/sm_calculator-0.0.1.1-Source.tar.gz - sources archive package. Testing of builds: -------------------- Unit tests are launched during all builds on all platforms (Windows/Linux). Soultion contains follow unit tests: sm_calc_test - basic unit test (application sm_calc_test), which provides testing of functionality, declared and implemented in files sm_calc_proc.h and sm_calc_proc.c; sm_calc_test_files_01 - unit test (application sm_calc_test_files), that provides testing of functionality via call of main module function (from sm_calc.c), using options: --in_file=./sm_calc_test.in.01.txt --out_file=./sm_calc_test.out.01.txt ; sm_calc_test_files_02 - ... --in_file=./sm_calc_test.in.02.txt --out_file=./sm_calc_test.out.02.txt ; sm_calc_test_files_03 - ... --in_file=./sm_calc_test.in.03.txt --out_file=./sm_calc_test.out.03.txt ; sm_calc_test_files_04 - ... --in_file=./sm_calc_test.in.04.txt --out_file=./sm_calc_test.out.04.txt ; sm_calc_test_files_05 - ... --in_file=./sm_calc_test.in.05.txt --out_file=./sm_calc_test.out.05.txt ; sm_calc_test_files_06 - ... --in_file=./sm_calc_test.in.06.txt --out_file=./sm_calc_test.out.06.txt ; sm_calc_test_files_07 - ... --in_file=./sm_calc_test.in.07.txt --out_file=./sm_calc_test.out.07.txt ; m_calc_test_expr - unit test (application m_calc_test_expr), that provides testing of functionality via cal of main module function (from sm_calc.c), using option: --expression="pow_^2(sin(pi/2))+pow_^2(cos(pi/2))+24.*2/12.0+exp-5.0;" . Solution contains follow files, which are used/created by unit tests: - files, which contain suite of expressions, which are tested by sm_calc_test_files unit test application: sm_calc_test.in.01.txt sm_calc_test.in.02.txt sm_calc_test.in.03.txt sm_calc_test.in.04.txt sm_calc_test.in.05.txt sm_calc_test.in.06.txt sm_calc_test.in.07.txt - files, which contain execution results of sm_calc_test_files and processing of sm_calc_test.in.xx.txt: sm_calc_test.out.01.txt sm_calc_test.out.02.txt sm_calc_test.out.03.txt sm_calc_test.out.04.txt sm_calc_test.out.05.txt sm_calc_test.out.06.txt sm_calc_test.out.07.txt - temporary file, that contain execution result of sm_calc_test_expr: sm_calc_test.out.expr.txt - files, which contain true/correct execution results of sm_calc_test_files and processing of sm_calc_test.in.xx.txt; these files should be compared: sm_calc_test.check.xx.txt <--> sm_calc_test.out.xx.txt: sm_calc_test.check.01.txt sm_calc_test.check.02.txt sm_calc_test.check.03.txt sm_calc_test.check.04.txt sm_calc_test.check.05.txt sm_calc_test.check.06.txt sm_calc_test.check.07.txt After execution of unit tests sm_calc_test_files_xx developer should compare files sm_calc_test.out.xx.txt and correspondent sm_calc_test.check.xx.txt . Directories /tests/ and /_cmake/_build/tests/ - after build contain some scripts: sm_calc_test_files.check.bat - batch (for Windows platform) script file, that compares files (sm_calc_test.check.xx.txt <--> sm_calc_test.out.xx.txt), using DIFF tool; sm_calc_test_files.check.sh - bash (for Linux platform) script file, that compares files (sm_calc_test.check.xx.txt <--> sm_calc_test.out.xx.txt), using DIFF tool; sm_calc_test_files.check.py - Python 3 (multi-platform) script file, that compares files (sm_calc_test.check.xx.txt <--> sm_calc_test.out.xx.txt) (don't need any comparing tools). Before execution of sm_calc_test_files.check.bat or sm_calc_test_files.check.sh developer can change path to DIFF tool, if it's necessary. Script sm_calc_test_files.check.py doesn't need any comparing tool and makes it, using Python API. Developer can use sm_calc_test_files.check.bat - on Windows platform sm_calc_test_files.check.sh - on Linux platform or sm_calc_test_files.check.py - multi-platform for comparing files sm_calc_test.out.xx.txt and sm_calc_test.check.xx.txt. Comparing files: sm_calc_test.out.xx.txt and sm_calc_test.check.xx.txt developer can find, if unit tests sm_calc_test_files_xx have been executed with errors (if grammar of expressions in files sm_calc_test.in.xx.txt is correct, but solving of expressions isn't). -------------------- Copyright (C) 2020 SManSoft Sergey Manoylo