From 073d102112a293a611656f33eadb9d5f063cb32c Mon Sep 17 00:00:00 2001 From: Mike Karlesky Date: Tue, 16 Apr 2024 22:57:47 -0400 Subject: [PATCH] Documentation and formatting MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Updated README with corrections to CLI notes, developer instructions, and more documentation links - Replaced Unicode • with * to ensure terminal support --- README.md | 173 +++++++++++++++++++++++++++++++++------------ bin/cli.rb | 44 ++++++------ bin/cli_handler.rb | 4 +- 3 files changed, 150 insertions(+), 71 deletions(-) diff --git a/README.md b/README.md index 898a3b4c..72386df9 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ Ceedling works the way developers want to work. It is flexible and entirely command-line driven. It drives code generation and command line tools for you. All generated and framework code is easy to see and understand. -Ceedling's features support all types of C development from low-level embedded +Ceedling’s features support all types of C development from low-level embedded to enterprise systems. No tool is perfect, but it can do a lot to help you and your team produce quality software. @@ -69,7 +69,7 @@ library builds & dependency management, and more. **[Submit an issue][ceedling-issues]** at this repo. * Trying to understand features or solve a testing problem? Hit the **[discussion forums][forums]**. -* Paid training, customizations, and support contracts are avaialble by +* Paid training, customizations, and support contracts are available by **[contacting ThingamaByte][thingama-contact]**. The ThrowTheSwitch community follows a **[code of conduct](docs/CODE_OF_CONDUCT.md)**. @@ -305,7 +305,7 @@ A variety of options for [support][TTS-help] exist as well. ## Ceedling docs -**[Usage help][ceedling-packet]** (a.k.a. _Ceedling Packet_), **[release notes][release-notes]**, **[breaking changes][breaking-changes]**, a variety of guides, and much more exists in **[docs/](docs/)**. +**[Usage help][ceedling-packet]** (a.k.a. _Ceedling Packet_), **[release notes][release-notes]**, **[breaking changes][breaking-changes]**, **[changelog][changelog]**, a variety of guides, and much more exists in **[docs/](docs/)**. ## Library and courses @@ -322,6 +322,7 @@ Matt Chernosky’s **[detailed tutorial][tutorial]** demonstrates using Ceedling [ceedling-packet]: docs/CeedlingPacket.md [release-notes]: docs/ReleaseNotes.md [breaking-changes]: docs/BreakingChanges.md +[changelog]: docs/Changelog.md [TTS]: https://throwtheswitch.org [library]: http://www.throwtheswitch.org/library [running-options]: http://www.throwtheswitch.org/build/which @@ -338,8 +339,25 @@ Matt Chernosky’s **[detailed tutorial][tutorial]** demonstrates using Ceedling ### Docker image -A fully packaged [Ceedling Docker image][docker-image] containing Ruby, Ceedling, the GCC toolchain, and some helper scripts is also available. A Docker container is a self-contained, portable, well managed alternative to a local installation of Ceedling. +Fully packaged [Ceedling Docker images][docker-image] containing Ruby, Ceedling, the GCC toolchain, and more are also available. A Docker container is a self-contained, portable, well-managed alternative to a local installation of Ceedling. +From your local terminal after [installing Docker][docker-install]: + +_Note: [Helper scripts are available][docker-image] to simplify your command line and access advanced features._ + +```shell + > docker run -it --rm -v $PWD/my/project:/home/dev/project throwtheswitch/madsciencelab:latest +``` + +From within the `madsciencelab` container’s project working directory: + +```shell + > ceedling test:all +``` + +See the [Docker image documentation][docker-image] for all the details on how to use these containers. + +[docker-install]: https://www.docker.com/products/docker-desktop/ [docker-image]: https://hub.docker.com/r/throwtheswitch/madsciencelab ### Local installation @@ -349,8 +367,12 @@ A fully packaged [Ceedling Docker image][docker-image] containing Ruby, Ceedling ```shell > gem install ceedling ``` -1. Create an empty Ceedling project or add a Ceedling project file to - the root of your existing project. +1. Begin crafting your project: + 1. Create an empty Ceedling project. + ```shell + > ceedling new [] + ``` + 1. Or, add a Ceedling project file to the root of an existing code project. 1. Run tasks like so: ```shell > ceedling test:all release @@ -372,46 +394,54 @@ A fully packaged [Ceedling Docker image][docker-image] containing Ruby, Ceedling - inc/** ``` +See _[CeedlingPacket][ceedling-packet]_ for all the details of your configuration file. + [Ruby]: https://www.ruby-lang.org/ -## Creating a project +## Getting command line help -Creating a project with Ceedling is easy. Simply tell Ceedling the -name of the project, and it will create a directory with that name -and fill it with a default subdirectory structure and configuration -file. +For an overview of all commands, it’s as easy as… -```shell - > ceedling new YourNewProjectName +```sh + > ceedling help ``` -You can add files to your `src/` and `test/` directories, and they will -instantly become part of your test build. Need a different structure? -You can modify the `project.yml` file with your new path or tooling -setup. +For a detailed explanation of a single command… -You can upgrade to the latest version of Ceedling at any time, -automatically gaining access to any updates to Unity, CMock, and -CException that come with it. +```sh + > ceedling help +``` + +## Creating a project + +Creating a project with Ceedling is easy. Simply tell Ceedling the name of the +project, and it will create a directory with that name and fill it with a +default subdirectory structure and configuration file. An optional destination +path is also possible. ```shell - > gem update ceedling + > ceedling new YourNewProjectName ``` -## Installing local documentation +You can add files to your `src/` and `test/` directories, and they will +instantly become part of your test and/or release build. Need a different +structure? You can modify the `project.yml` file with your new path or +tooling setup. + +### Installing local documentation -Are you just getting started with Ceedling? Maybe you'd like your +Are you just getting started with Ceedling? Maybe you’d like your project to be installed with some of its handy [documentation](docs/)? -No problem! You can do this when you create a new project. +No problem! You can do this when you create a new project… ```shell > ceedling new --docs MyAwesomeProject ``` -## Attaching a Ceedling version to your project +### Attaching a Ceedling version to your project Ceedling can be installed as a globally available Ruby gem. Ceedling can -also deploy all of its guts into your project instead. This allows it to +also deploy all its guts into your project instead. This allows it to be used without worrying about external dependencies. More importantly, you don’t have to worry about Ceedling changing outside of your project just because you updated your gems. No need to worry about changes in @@ -424,34 +454,44 @@ your project: > ceedling new --local YourNewProjectName ``` -This will install all of Unity, CMock, CException, and Ceedling itsef +This will install all of Unity, CMock, CException, and Ceedling itself into a new folder `vendor/` inside your project `YourNewProjectName/`. -It will still create a simple empty directory structure for you with -`src/` and `test/` folders. +It will create the same simple empty directory structure for you with +`src/` and `test/` folders as the standard `new` command. -If you want to force a locally installed version of Ceedling to upgrade -to match your latest gem later, no problem. Just do the following: +## Upgrading / updating Ceedling + +You can upgrade to the latest version of Ceedling at any time, automatically +gaining access to any accompanying updates to Unity, CMock, and CException. + +To update a locally installed gem… ```shell - > ceedling upgrade --local YourNewProjectName + > gem update ceedling ``` -Just like with the `new` command, an `upgrade` should be executed from -from within the root directory of your project. +Otherwise, if you are using the Docker image, you may upgrade by pulling +a newer version of the image… -Are you afraid of losing all your local changes when this happens? You -can prevent Ceedling from updating your project file by adding -`--no-configs`. +```shell + > docker pull throwtheswitch/madsciencelab: +``` + +If you want to force a vendored version of Ceedling inside your project to +upgrade to match your latest gem, no problem. Just do the following… ```shell - > ceedling upgrade --local --no-configs YourSweetProject + > ceedling upgrade --local YourNewProjectName ``` +Just like with the `new` command, an `upgrade` should be executed from +within the root directory of your project. + ## Git integration Are you using Git? You might want Ceedling to create a `.gitignore` -which ignores the build folder (while retaining control of the artifacts -folder). This will also add a `.gitkeep` file to your `test/support` folder. +that ignores the build folder while retaining control of the artifacts +folder. This will also add a `.gitkeep` file to your `test/support` folder. You can enable this by adding `--gitsupport` to your `new` call. ```shell @@ -461,7 +501,9 @@ You can enable this by adding `--gitsupport` to your `new` call. # 💻 Contributing to Ceedling Development -## Alternate installation +## Alternate installation for development + +After installing Ruby… ```shell > git clone --recursive https://github.com/throwtheswitch/ceedling.git @@ -471,7 +513,7 @@ You can enable this by adding `--gitsupport` to your `new` call. ``` The Ceedling repository incorporates its supporting frameworks and some -plugins via git submodules. A simple clone may not pull in the latest +plugins via Git submodules. A simple clone may not pull in the latest and greatest. The `bundle` tool ensures you have all needed Ruby gems installed. If @@ -496,19 +538,56 @@ Gemfile.lock. Ceedling uses [RSpec] for its tests. -To run all tests run the following from the root of your local +To run all tests you may run the following from the root of your local Ceedling repository. ```shell > bundle exec rake ``` -To run individual test files and perform other tasks, use the -available Rake tasks. From the root of your local Ceedling repo, -list those task like this: +The above is a time consuming but complete test process. Generally, most +developers can run the following from the root of your locally cloned +repo instead. + +```shell + > rake ci +``` + +To run individual test files (Ceedling’s Ruby-based tests, that is) and +perform other tasks, use the available Rake tasks. From the root of your +local Ceedling repo, list those task like this: ```shell > rake -T ``` -[RSpec]: https://rspec.info \ No newline at end of file +[RSpec]: https://rspec.info + +## Working in `bin/` vs. `lib/` + +Most of Ceedling’s functionality is contained in the application code residing +in `lib/`. Ceedling’s command line handling, startup configuration, project +file loading, and mixin handling are contained in a “bootloader” in `bin/`. +The code in `bin/` is the source of the `ceedling` command line tool and +launches the application from `lib/`. + +Depending on what you’re working on you may need to run Ceedling using +a specialized approach. + +If you are only working in `lib/`, you can: + +1. Run Ceedling using the `ceedling` command line utility you already have + installed. The code in `bin/` will run from your locally installed gem or + from within your Docker container and launch the Ceedling application for + you. +1. Modify a project file by setting a path value for `:project` ↳ `:which_ceedling` + that points to the local copy of Ceedling you cloned from the Git repository. + See _CeedlingPacket_ for details. + +If you are working in `bin/`, running `ceedling` at the command line will not +call your modified code. Instead, you must execute the path to the executable +`ceedling` in the `bin/` folder of the local Ceedling repository you are +working on. + + + diff --git a/bin/cli.rb b/bin/cli.rb index f2acb1fd..d2a44631 100755 --- a/bin/cli.rb +++ b/bin/cli.rb @@ -146,9 +146,9 @@ def initialize(args, config, options) Optional Flags: - • #{LONGDOC_PROJECT_FLAG} + * #{LONGDOC_PROJECT_FLAG} - • #{LONGDOC_MIXIN_FLAG} + * #{LONGDOC_MIXIN_FLAG} LONGDESC def help(command=nil) # Get unfrozen copies so we can add / modify @@ -182,14 +182,14 @@ def help(command=nil) Optional Flags: - • #{LONGDOC_LOCAL_FLAG} + * #{LONGDOC_LOCAL_FLAG} - • #{LONGDOC_DOCS_FLAG} + * #{LONGDOC_DOCS_FLAG} - • `--configs` add a starter project configuration file into the root of the + * `--configs` add a starter project configuration file into the root of the new project. - • `--force` overrides protectons preventing a new project from overwriting an + * `--force` overrides protectons preventing a new project from overwriting an existing project. This flag completely destroys anything found in the target path for the new project. LONGDESC @@ -225,7 +225,7 @@ def new(name, dest=nil) Optional Flags: - • `--project` specifies a filename (optionally with leading path) for the + * `--project` specifies a filename (optionally with leading path) for the project configuration file used in the project existence check. Otherwise, the default ./#{DEFAULT_PROJECT_FILENAME} at the root of the project is checked. @@ -266,25 +266,25 @@ def upgrade(path) Optional Flags: - • #{LONGDOC_PROJECT_FLAG} + * #{LONGDOC_PROJECT_FLAG} - • #{LONGDOC_MIXIN_FLAG} + * #{LONGDOC_MIXIN_FLAG} - • `--verbosity` sets the logging level. + * `--verbosity` sets the logging level. - • `--log` enables logging to the default filename and path location within your + * `--log` enables logging to the default filename and path location within your project build directory. - • `--logfile` enables logging to the specified log filepath + * `--logfile` enables logging to the specified log filepath (ex: my/path/file.log). - • `--graceful-fail` ensures an exit code of 0 even when unit tests fail. See + * `--graceful-fail` ensures an exit code of 0 even when unit tests fail. See documentation for full details. - • `--test-case` sets a test case name matcher to run only a subset of test + * `--test-case` sets a test case name matcher to run only a subset of test suite’s unit test cases. See documentation for full details. - • `--exclude-test-case` is the inverse of `--test-case`. See documentation for + * `--exclude-test-case` is the inverse of `--test-case`. See documentation for full details. LONGDESC def build(*tasks) @@ -319,11 +319,11 @@ def build(*tasks) Optional Flags: - • #{LONGDOC_PROJECT_FLAG} + * #{LONGDOC_PROJECT_FLAG} - • #{LONGDOC_MIXIN_FLAG} + * #{LONGDOC_MIXIN_FLAG} - • `--app` loads the Ceedling application that adds various settings, merges defaults, loads + * `--app` loads the Ceedling application that adds various settings, merges defaults, loads configration changes due to plugins, and validates the configuration. Disabling the application dumps the project configuration after any mixins but before any application manipulations. LONGDESC @@ -350,9 +350,9 @@ def dumpconfig(filepath, *sections) Optional Flags: - • #{LONGDOC_PROJECT_FLAG} + * #{LONGDOC_PROJECT_FLAG} - • #{LONGDOC_MIXIN_FLAG} + * #{LONGDOC_MIXIN_FLAG} LONGDESC def environment() # Get unfrozen copies so we can add / modify @@ -396,9 +396,9 @@ def examples() Optional Flags: - • #{LONGDOC_LOCAL_FLAG} + * #{LONGDOC_LOCAL_FLAG} - • #{LONGDOC_DOCS_FLAG} + * #{LONGDOC_DOCS_FLAG} NOTE: `example` is destructive. If the destination path is a previoulsy created example project, `ceedling example` will forcibly overwrite the contents. diff --git a/bin/cli_handler.rb b/bin/cli_handler.rb index 85bfe124..ae28f68e 100755 --- a/bin/cli_handler.rb +++ b/bin/cli_handler.rb @@ -262,7 +262,7 @@ def environment(env, app_cfg, options) output = "\nEnvironment variables:\n" env_list.sort.each do |line| - output << " • #{line}\n" + output << " * #{line}\n" end @streaminator.stream_puts( output + "\n" ) @@ -276,7 +276,7 @@ def list_examples(examples_path) output = "\nAvailable example projects:\n" - examples.each {|example| output << " • #{example}\n" } + examples.each {|example| output << " * #{example}\n" } @streaminator.stream_puts( output + "\n" ) end