From: Fletcher T. Penney Date: Thu, 12 Nov 2015 14:33:09 +0000 (-0500) Subject: Update README handling to autogenerate and copy to top-level; configure cmake to... X-Git-Tag: 0.1.0a~21 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=1bfbae089408e887cfbbb4b763bd6e91776ca92b;p=multimarkdown Update README handling to autogenerate and copy to top-level; configure cmake to reference this top-level README for installer/doxygen/etc. --- diff --git a/CMakeLists.txt b/CMakeLists.txt index 0e2bc95..0040eb1 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -48,9 +48,10 @@ configure_file ( "${PROJECT_BINARY_DIR}/template.h" ) +# Update the project README, to pull in new version #, etc. configure_file ( "${PROJECT_SOURCE_DIR}/templates/README.md.in" - "${PROJECT_BINARY_DIR}/README.md" + "${CMAKE_CURRENT_LIST_DIR}/README.md" ) configure_file ( @@ -219,7 +220,7 @@ endif (WIN32) # You're largely on your own here -install (FILES ${CMAKE_CURRENT_BINARY_DIR}/README.md ${PROJECT_SOURCE_DIR}/LICENSE.txt +install (FILES ${CMAKE_CURRENT_LIST_DIR}/README.md ${PROJECT_SOURCE_DIR}/LICENSE.txt DESTINATION . ) diff --git a/README.md b/README.md index 8d2e04a..dac43e8 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,15 @@ +## About ## -# Introduction # +| | | +| ---------- | ------------------------- | +| Title: | Some Project | +| Author: | Somebody | +| Date: | 2015-06-05 | +| Copyright: | Copyright © 2015 Somebody. | +| Version: | 1.0.1 | + + +## Introduction ## This template was created out of a desire to simplify some of the setup and configuration that I was doing over and over each time I started a new project. @@ -28,9 +38,9 @@ Additionally, I wanted to try to start encouraging some "better practices" `cmake` to combine those elements to ensure consistency across source code and README files. -4. Documentation -- some default setup to allow for [doxygen]-generated +4. Documentation -- some default setup to allow for [Doxygen]-generated documentation. The generated `README.md` file is used as the main - page, and the source c/header files are included. Naturally, doxygen + page, and the source c/header files are included. Naturally, Doxygen is a complex system, so you're responsible for figuring out how to properly document your code. @@ -51,10 +61,10 @@ Additionally, I wanted to try to start encouraging some "better practices" [tdd]: https://en.wikipedia.org/wiki/Test-driven_development [cmake]: http://www.cmake.org/ [CuTest]: http://cutest.sourceforge.net -[doxygen]: http://www.stack.nl/~dimitri/doxygen/ +[Doxygen]: http://www.stack.nl/~dimitri/doxygen/ -# How do I use it? # +## How do I use it? ## You can download the source from [github] and get to work. The file "IMPORTANT" contains instructions on the various build commands you can use. @@ -62,7 +72,7 @@ contains instructions on the various build commands you can use. I recommend using the following script to automatically create a new git repo, pull in the default project template, and configure git-flow. You simply have -to rename your project from `new-project` to whatever you desire: +to rename your project directory from `new-project` to whatever you desire: #!/bin/sh @@ -80,8 +90,8 @@ to rename your project from `new-project` to whatever you desire: git checkout develop -Using this approach, you can define your own "origin" remote if you like, but -the "template" remote can be used to update the core project files should any +Using this approach, you can define your own `origin` remote if you like, but +the `template` remote can be used to update the core project files should any improvements come about: git checkout develop @@ -97,7 +107,105 @@ projects will need some customization. [github]: https://github.com/fletcher/c-template -# License # +## Configuration ## + + +### CMakeLists.txt File ### + +First, you should update the project information under the "Define Our Project" +section, including the title, description, etc. This information will be used +to update the README, as well as to create the `version.h` file so that the +project can have access to its own version number. + +You will then need to update the various groups in the "Source Files" section +so that Cmake will be able to determine which files are used to build your +project. For reasons that will become clear later, try to follow the +suggestions for the different groups of files. + +You then need to define your targets, such as a library, or executable, etc. +Obviously, this will depend on the needs of your project. You can also add +custom steps based on the Target OS (OS X, Windows, *nix, etc.). + +You can use CPack to generate installers for your software. This can be +complex, and you will need to modify this section heavily. + +CuTest is used by default to provide unit testing (see below), but you +can also use CMake/CTest to provide integration testing. Again, this will +be up to you to configure. + + +### CuTest ### + +[CuTest] provides a means to integrate unit testing with your C source code. +Once you get the hang of it, it's easy to use. + + +### Doxygen ### + +[Doxygen] is used to generate documentation from the source code itself. +Properly configuring your source for this is up to you. You can modify the +`doxygen.conf.in` template with your desired settings as desired, but most +of the basics are handled for you based on your CMake configuration. + + +### Makefile ### + +The overall build process is controlled by the master `Makefile`. It provides +the following commands: + + make + make release + +Generate the CMake build files for use or distribution. Once complete you will +need to change to the `build` directory and run `make`, `make test`, and +`cpack` as desired. + + make zip + +Direct CPack to create a zip installer rather than a graphical installer. + + make debug + +Generate build files for [CuTest] unit testing. In the `build` directory, +run `make`, then `make test`. + + make analyze + +If you have `clang` installed, this will generate debug build files with the +`scan-build` command. In the `build` directory, run `scan-build -V make` +to compile the software and view the static analysis results. + + make xcode + +Build a project file for Xcode on OS X. + + make windows + make windows-zip + make windows-32 + make windows-zip-32 + +Use the MinGW software to cross-compile for Windows on a *nix machine. You can +specify the 32 bit option, and also the zip option as indicated. + + make documentation + +Build the [Doxygen]-generated documentation. + + make clean + +Clean out the `build` directory. Be sure to run this before running another +command. + + +## Source File Templates ## + +In the `templates` directory are two files, `template.c.in` and +`template.h.in`. These are used to create default source files that include +the project title, copyright, license, etc. They are also set up to include +some example information for [Doxygen] and [CuTest]. + + +## License ## The `c-template` project is released under the MIT License. diff --git a/templates/README.md.in b/templates/README.md.in index 12f6a3d..ffe0eba 100644 --- a/templates/README.md.in +++ b/templates/README.md.in @@ -1,16 +1,208 @@ ## About ## -| | | -| ---------- | ------------------------- | -| Title: | @My_Project_Title@ | -| Author: | @My_Project_Author@ | -| Date: | @My_Project_Revised_Date@ | -| Copyright: | @My_Project_Copyright@ | -| Version: | @My_Project_Version@ | +| | | +| ---------- | ------------------------- | +| Title: | @My_Project_Title@ | +| Author: | @My_Project_Author@ | +| Date: | @My_Project_Revised_Date@ | +| Copyright: | @My_Project_Copyright@ | +| Version: | @My_Project_Version@ | ## Introduction ## +This template was created out of a desire to simplify some of the setup and +configuration that I was doing over and over each time I started a new project. +Additionally, I wanted to try to start encouraging some "better practices" +(though not necessarily "best practices"): + +1. [Test-driven development][tdd] -- My development of MultiMarkdown + focused on integration testing, but really had no unit testing to + speak of. Some newer projects I began working on were a bit math- + heavy, and ensuring that each piece works properly became even more + important. It was also nice to be able to actually develop code that + could do *something* (via the test suite), even though the project as + a whole was nowhere near complete.) To accomplish this, I include the + [CuTest] project to support writing tests for your code. + +2. Use of the [cmake] build system. `cmake` is not perfect by any + means, but it does offer some very useful features and a means for + better integrating the compilation and packaging/installation aspects + of development. Rather than reinventing the wheel each time, this + setup incorporates basic `cmake` functionality to make it easy to + control how your project is compiled, and includes automated generation + of the test command. + +3. Templates -- `cmake` has a reasonable templating system, so that you + can define basic variables (e.g. author, project name, etc.) and allow + `cmake` to combine those elements to ensure consistency across source + code and README files. + +4. Documentation -- some default setup to allow for [Doxygen]-generated + documentation. The generated `README.md` file is used as the main + page, and the source c/header files are included. Naturally, Doxygen + is a complex system, so you're responsible for figuring out how to + properly document your code. + +5. Simplify `git` a touch -- In my larger projects, I make heavy use of + git modules. One project may make use of 20-30 modules, which are + designed to be re-usable across other projects. I found that I was + spending too much time making sure that I had the latest version + of a module checked out, so I created two scripts to help me keep + my modules in line: `link_git_modules` and `update_git_modules`. + You run the `link` script once to ensure that your modules are properly + set up, and can then run the `update` script at any time to be sure + you've pulled the latest version. One advantage of this is that your + modules are set to a branch, rather than just a detached commit. It + may or may not work for your needs, but it saves me a bunch of time + and headache. + + +[tdd]: https://en.wikipedia.org/wiki/Test-driven_development +[cmake]: http://www.cmake.org/ +[CuTest]: http://cutest.sourceforge.net +[Doxygen]: http://www.stack.nl/~dimitri/doxygen/ + + +## How do I use it? ## + +You can download the source from [github] and get to work. The file "IMPORTANT" +contains instructions on the various build commands you can use. + + +I recommend using the following script to automatically create a new git repo, +pull in the default project template, and configure git-flow. You simply have +to rename your project directory from `new-project` to whatever you desire: + + + #!/bin/sh + + git init new-project + + cd new-project + + git remote add "template" https://github.com/fletcher/c-template.git + + git pull template master + + git flow init -d + + git checkout develop + + +Using this approach, you can define your own `origin` remote if you like, but +the `template` remote can be used to update the core project files should any +improvements come about: + + git checkout develop + git merge template master + +**NOTE**: `cmake` is a complex suite of utilities, and if you have trouble you +will need to get support elsewhere. If you find errors in this template, by +all means I want to hear about them and fix them, but this is just a basic +framework to get you started. In all likelihood, all but the most basic +projects will need some customization. + + +[github]: https://github.com/fletcher/c-template + + +## Configuration ## + + +### CMakeLists.txt File ### + +First, you should update the project information under the "Define Our Project" +section, including the title, description, etc. This information will be used +to update the README, as well as to create the `version.h` file so that the +project can have access to its own version number. + +You will then need to update the various groups in the "Source Files" section +so that Cmake will be able to determine which files are used to build your +project. For reasons that will become clear later, try to follow the +suggestions for the different groups of files. + +You then need to define your targets, such as a library, or executable, etc. +Obviously, this will depend on the needs of your project. You can also add +custom steps based on the Target OS (OS X, Windows, *nix, etc.). + +You can use CPack to generate installers for your software. This can be +complex, and you will need to modify this section heavily. + +CuTest is used by default to provide unit testing (see below), but you +can also use CMake/CTest to provide integration testing. Again, this will +be up to you to configure. + + +### CuTest ### + +[CuTest] provides a means to integrate unit testing with your C source code. +Once you get the hang of it, it's easy to use. + + +### Doxygen ### + +[Doxygen] is used to generate documentation from the source code itself. +Properly configuring your source for this is up to you. You can modify the +`doxygen.conf.in` template with your desired settings as desired, but most +of the basics are handled for you based on your CMake configuration. + + +### Makefile ### + +The overall build process is controlled by the master `Makefile`. It provides +the following commands: + + make + make release + +Generate the CMake build files for use or distribution. Once complete you will +need to change to the `build` directory and run `make`, `make test`, and +`cpack` as desired. + + make zip + +Direct CPack to create a zip installer rather than a graphical installer. + + make debug + +Generate build files for [CuTest] unit testing. In the `build` directory, +run `make`, then `make test`. + + make analyze + +If you have `clang` installed, this will generate debug build files with the +`scan-build` command. In the `build` directory, run `scan-build -V make` +to compile the software and view the static analysis results. + + make xcode + +Build a project file for Xcode on OS X. + + make windows + make windows-zip + make windows-32 + make windows-zip-32 + +Use the MinGW software to cross-compile for Windows on a *nix machine. You can +specify the 32 bit option, and also the zip option as indicated. + + make documentation + +Build the [Doxygen]-generated documentation. + + make clean + +Clean out the `build` directory. Be sure to run this before running another +command. + + +## Source File Templates ## + +In the `templates` directory are two files, `template.c.in` and +`template.h.in`. These are used to create default source files that include +the project title, copyright, license, etc. They are also set up to include +some example information for [Doxygen] and [CuTest]. ## License ## diff --git a/templates/doxygen.conf.in b/templates/doxygen.conf.in index 934549d..348182e 100644 --- a/templates/doxygen.conf.in +++ b/templates/doxygen.conf.in @@ -654,7 +654,7 @@ WARN_LOGFILE = # directories like "/usr/src/myproject". Separate the files or directories # with spaces. -INPUT = @PROJECT_BINARY_DIR@/README.md @doxygen_src_files@ @doxygen_header_files@ +INPUT = @CMAKE_CURRENT_LIST_DIR@/README.md @doxygen_src_files@ @doxygen_header_files@ # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is