2023-2-WS_group_project_cstools101/docs/CeedlingUpgrade.md

# Upgrading Ceedling

You'd like to stay in sync with the latest Ceedling... and who wouldn't? Depending on 
how you've made use of Ceedling, that may vary slightly. No matter what, though, our first
step is to update Ceedling itself.

## Step 1: Update Ceedling Itself

```
gem update ceedling
```

That should do it... unless you don't have a valid connection to the internet. In that case,
you might have to download the gem from rubygems.org and then install it manually:

```
gem update ceedling --local=ceedling-filename.zip
```

## Step 2: Udpate Projects Using Ceedling

When you set up your project(s), it was either configured to use the gem directly, or it was
configured to install itself locally (often into a vendor directory).

For projects that are of the first type, congratulations, you're finished. The project will
automatically use the new ceedling. There MAY be things that need to be tweaked if features have
moved significantly. (And we apologize if that's your situation... as we get to version 1, we're
going to have a stronger focus on backwards compatibility). If your project isn't working perfectly, 
skip down to Step 3.

If the project was installed to have a copy of ceedling locally, you have a choice. You may 
choose to continue to run THIS project on the old version of Ceedling. Often this is the
preferred method for legacy projects which only get occasional focus. Why go through the effort 
of updating for new tools if it's serving its purpose and you're unlikely to actually use the new
features?

The other choice, of course, is to update it. To do so, we open a command prompt and address ceedling 
from *outside* the project. For example, let's say we have the following structure:

 - projects
    - myproject
        - project.yml
        - src
        - tgt
        - vendor

In this case, we'd want to be in the `projects` directory. At that point, we can ask Ceedling to
update our project.

```
ceedling upgrade myproject
```

Ceedling will automatically look for your project yaml file and do its best to determine what needs
to be updated. If installed locally, this will mean copying the latest copy of Unity, CMock, and
Ceedling. It will also involve copying documentation, if you had that installed.

## Step 3: Solving Problems

We wish every project would update seamlessly... unfortunately there is a lot of customization that
goes into each project, and Ceedling often isn't aware of all of these. To make matter worse, Ceedling
has been in pre-release for awhile, meaning it occasionally has significant changes that may break
current installations. We've tried to capture the common ones here:

### rakefile

Ceedling is built in a utility called Rake. In the past, rake was the method that the user actually
interacted with Ceedling. That's no longer the case. Using a modern version of Ceedling means that
you issue commands like `ceedling test:all` instead of `rake test:all`. If you have a continuous 
integration server or other calling service, it may need to be updated to comply.

Similarly, older versions of Ceedling actually placed a rakefile in the project directory, allowing 
the project to customize its own flow. For the most part this went unused and better ways were later
introduced. At this point, the `rakefile` is more trouble than its worth and often should just be 
removed. 

### plugins

If you have custom plugins installed to your project, the plugin architecture has gone through some 
revisions and it may or may not be compatible at this time. Again, this is a problem which should
not exist soon.