...

Before we get started if you have not yet done so, please read up on Software 101 in particular, the Coding Standards! These will be necessary to actually do any development on the car. It is also recommended that you spend some time working with the MSP430 launchpads which were part of the architecture from the previous vehicle MSXI and will provide a good basis for getting started. 

...

• Compiler: GCC ARM
  • A compiler builds human readable source code into a machine readable target language, usually a machine executable or binary for a specific architecture. GCC ARM compiles C code into machine readable .elf, .hex or .bin files which can be flashed onto the MCU. GCC ARM is the standard open source compiler for ARM architecture. Compilers are powerful and often catch typos, errors, and warnings; they also optimize code for efficiency or size. The compiler flags set these behaviors of the compiler.
• Build Tools: GNU Make and GNU Linker aka ld
  • Build tools usually instruct the compiler on where the source files it is building are located and which files to look at in order to build the target program. Often a Linker will be used with a Makefile to build a collection of C and header files into a standard library which can be included in your program. GNU Make and Linker are long-standing open source standard build tools used by many developers, although many alternatives do exist.
• Linter: cpplint 
  • A linter is a program that checks the style of source code for errors. Some linters also perform static analysis, ours does not, which look to catch programming errors before the code is executed. cpplint is Google's open source linter for C/C++ programs, note that our Coding Standards closely follow Google's and as a result, this linter works well for us. It will often be more pedantic than we need but it is a good tool to useThe linter has been modified to support some slightly different standards and will be less pedantic.
• Flasher: st-link/GDB or OpenOCD
  • A flasher will transfer firmware (our compiled program) onto the MCU. Typically, this is done with a special cable or by a chip on the PCB and requires flashing software to transfer the contents of the source code into the memory of the MCU. For our purposes, we will be using st-link with GDB for debug which is the chip manufacturer supported method or OpenOCD the open source version.
• IDEs: Eclipse or any text editor (Core members like: Vim, Sublime Text and Visual Studio Code)
  • Anyone just starting out and especially those using Windows are strongly encouraged to use the Eclipse IDE which is one of the few ways to get a working Toolchain on a Windows machine. Note that we will not be supporting any issues you may encounter using other methods on Windows although, we will also support Linux if you want a VM or dual boot but you will need to figure out the install on your own. 
• Source Control: GitHub
  • We use GitHub for our source and versioning control. In order to contribute to the codebase, you will also need to start using GitHub. If you are new to GitHub you may want to check out these guides. We have tight controls on out git repositories and require all commits to come from pull requests and that they are squashed prior to submitting.

...

Step 3: Install Python version 2.7 and get cpplint using pip from the command line: (You can also clone it off the GitHub repo here)

$ pip install cpplint

You you will need to add both Python2.7 and cpplint to Python 2.7 to your environment path so that the makefile runs the lint correctly.

Step 4: In theory that should be everything. Try it by cloning a copy of the template from  TODO "here " and building it in Eclipse.

...

Step 2: Download and unpack the GCC ARM Linux tarball from here. Alternatively install it from your package repository if you have one.

Step 3: Download cpplint using pip or from the package repository 

$ pip install cpplint

Python 2.7 (if you didn't in step 1) and add it to your ~/.bashrc or ~/.bash_profile if is isn't already in your PATH. 

Step 4: Install st-link or OpenOCD, they may be in your package repository but you can always build from source. 

Step 5: In theory that is everything, assuming your distribution is sane and already has gcc and make installed. Feel free to grab an IDE or text editor if you don't already have one you like. The link in Step 2 of the Windows guide has a tutorial for setting up in Eclipse.

Step 6: Try cloning a copy of the template from TODO "here" and building it by navigating to the directory and typing 

...

I don't own a Mac nor do any of the software core members. All the tools should, in theory, be OS X compatible so you can try building the same tools that those using the Linux guide do. Alternatively, you can follow the Windows instructions although you shouldn't have to fiddle with Path variables as much.

A more detailed guide is coming Soon^TM 

Project Template

The package template contains five directories, a Makefile and a README. Use this for starting new projects only. Existing projects will have their own repositories which will share a copy of libraries, linker, and extra. 

Linting

As mentioned linting checks to ensure code meets our style guides. A custom version of cpplint.py is included in the package template it has been altered to support our styleguide. Calder Kitagawa is the maintainer so if you think there is a bug or style violation it is too pedantic/permissive reach out and ask. A Git hook will prevent you from pushing any code with errors so lint often you don't want to rewrite a whole file just because you messed up on style!

$ make lint
OR
$ python cpplint <file(s)>
OR
$ python2 cpplint <file(s)>

Running make lint executes cpplint on all files in src and inc. If you want to just lint specific files use python cpplint. Note the cpplint will accept wildcards in the file definitions.

Makefile

As mentioned, a Makefile tells the compiler what to build and where to find those items. This Makefile is no different, it automatically links and builds a file called main.elf and the STM Peripheral library (THIS LIBRAY FEATURES A HAL DO NOT USE IT WE ARE MAKING OUR OWN) which is located in the libraries directory. The libraries can be included without needing a relative path as can any header files you write and place in the inc directory. The linker directory contains the linker files to build the libraries. The extra folder contains configuration options for making an OpenOCD binary. Any program files you create should go in the src directory and any drivers should go into inc. The README will contain more detailed information and the Makefile does have options for selecting source files.

Usage (Linux and OSX)

$ make

Builds the package assuming it isn't built already or modified

$ make all

Same as make

$ make clean

Removes the .elf, .map and .bin files from the package

$ make reallyclean

In addition to doing what make clean does it also cleans the library from the /libraries driectory

$ make program

Builds the OpenOCD binary