Last updated 28 February 2021
Source code is generally not included in Embed Software releases. It is made available via publicly-readable repositories on GitHub. This document describes how to get that source code into the right place, and how to set it up for building locally on your machine.
There are currently two types of buildable source code available:
For 8 bit PICs, the MPASM/MBLIB/MPLINK suite is used. Note that this is not compatible with the XC8 compiler and related tools. MPASM and XC8 have different binary formats, and can not be used with the same linker.
For 16 bit PICs and dsPICs, the XC16ASM assembler with its librarian and linker are used. Since the XC16 C compiler produces relocatable binary with the same format as the XC16 assembler, C and assembler source can be used in the same firmware. While most Embed source is in assembler, there is support for individual firmware modules written in C.
It is recommended that some version of the XC16 C compiler be installed. Most Embed code for the 16 bit parts only requires the assembler, and the free version of XC16 is sufficient to build any Embed code that is written in C.
Briefly, the process of setting up a system to build Embed source code is:
Each of these steps is detailed below.
Install Microsoft Visual Studio, which includes the C compiler, librarian, and linker. We have found versions 2014 and later to work. Earlier versions might work too.
Install Microchip MPLAB-X. This is free. If you have a paid version of XC16 installed, then don't install the optional free XC16. If not, install the free XC16. The Embed build tools do not need any other optional product, like the XC8 or XC32 compilers.
All Embed source code is kept in GIT repositories. GIT is assumed by parts of the Embed build system.
Go to the Embed downloads page and install the latest "Full Runtime" release. Make sure to reboot the system, if so directed, before proceeding.
Get used to the fact that most Embed programs are run from the command line. If you only want to clickety-click and aren't comfortable with the command shell (cmd.exe), then this software isn't for you.
While it is possible to run the programs some other way, like the "Run" dialog, this is a bad idea. These methods usually close the command shell window as soon as the program exits, so you won't be able to read error messages if something goes wrong, or even notice there were any errors.
This program searches your system for the required third party tools. It then leaves links and other information in known places so that the Embed programs and build scripts can find these tools.
Follow the instructions emitted by the program.
The program will ask you where you think certain tools are installed. The purpose of this is to limit the search tree to result in a faster search. We recommend that you don't try to limit the search tree. It may take an extra minute or two, but some components of some tools can be installed in unexpected places. This step only needs to be performed once.
If you install newer versions of third party tools at a later time, it may be necessary to re-run embed_extool because new versions are can be installed in different places. MSVC often does this. If you have a MSVC subscription that updates automatically, try running embed_extool when building host code suddenly stops working.
Run gitget_embed. This is a script that makes a local copy of all Embed public source repositories. Make sure not to supply any command line arguments.
This script will create new repositories. If a repository previously exists, it will be deleted and completely overwritten with the latest version of that repository from GitHub. If you have made your own changes to Embed source, save those changes elsewhere before running this script.
Run build_host. This is a script that updates the build scripts from the BUILDSCR repository, builds all the linkable libraries, then builds the executable programs.
This script will take minutes to complete, although it will show frequent activity on standard output.
After this completes, go to <embed>\source\escr. "<embed>" is the directory that you installed the Embed software to. The default is c:\embedinc, but you may have installed to a different location. If you installed the Embed software to the default location, then the full pathname above is "c:\embedinc\source\escr".
Run build_progs. This builds the executable programs from this source repository. The main executable program is ESCR.EXE, which is the Embed script intepreter. This could not be built earlier since it was in use and the system would not have allowed the file to be overwritten.
Source repositories are in the <embed>\source tree. Some are at the top level, while others are grouped in sub-directories. Each repository that contains anything buildable contains a script build that builds everything from that repository.
The top level build script usually just calls other more specific build scripts, like build_lib (builds host libraries), build_progs (builds executable programs), build_fw (builds firmware), etc.
Most parts of a builds run in the <embed>\src tree. Each top level directory in <embed>\source has a corresponding directory in <embed>\src. The SRC directory for a repository is usually the current working directory for tools run during the build. This is also where temporary and intermediate files are put.
In theory, everything in a SRC directory is derived from the source code in the corresponding SOURCE and other SOURCE directories. The SRC directories can be emptied, and everything rebuilt from source.
Some of the intermediate files can be large, and not needed after a build. Periodically cleaning out the SRC directory can be useful. It is usually a good idea to clean out the SRC directory before running a final build. This ensures that the build mechanism is really creating everything from source, and not accidentally relying on files left around from previous builds.
The scr_clean script is a easy way to clean out most files in the <embed>\src tree.
As mentioned earlier, Embed software is generally intended to be used from a command shell. It is useful for various tools and scripts to have the view of being "in" or working on a particular source repository. This is done with environment variable settings.
The source command goes to a particular source directory and sets up the environment accordingly. For example "source stuff" will set the working directory to the <embed>\source\stuff repository, set up the environment accordingly, and also do a git status -s -b (shows a quick list of files changed since the last commit).
Debugging options are indicated to the build tools via the DEBUG environment variable. This variable can contain a list of keywords that indicate enabled debug switches. See the debug doc file for details.
The source command initializes all debug switches to off, unless the DEBUGMASTER enviroment variable is previously set. Debug settings are intended to be temporary, being reset by source. DEBUGMASTER provides a way to set debug state that persists with the shell.
The DEBUG environment variable is parsed by the make_debug program, which can write out information in various file formats. The make_debug program is run in various parts of the build process. While not necessary, understanding the make_debug program can be useful for understanding the debugging environment in general. See the make_debug doc file for details.
Every repository containing buildable code contains a build_vars script. This is always run first by the other build scripts. The purpose of build_vars is to set up environment variables uniquely for building from that repository. Generic build scripts (not those specific to a source directory) often expect certain environment variables to give information about the specific build.
Host software is built with a nested set of scripts:
Builds the library from this repository. In production mode, the .lib file is moved into the <embed>\lib directory. In most cases, the library will have a Pascal (.ins.pas) and C (.h) include file. These are also copied into the <embed>\lib directory.
The build_lib script is called from the top level build script, but is also intended to be run directly by the user.
Builds all the host programs from this repository. The library, if any, is not rebuilt, so the latest previously-built version is used.
The build_progs script is called from the top level build script, but is also intended to be run directly by the user.
This script grabs files required by files to be built, and puts them in the expected places in the <embed>\src tree. Specifically, build_pasinit initializes for building Pascal source files. Most Embed host code is written in Pascal.
This script is intended to be run from other build scripts, not directly by the user. It may have side effects, like changing the working directory and setting environment variables that should exist only during a build.
build_pasinit calls build_vars.
Modules list file. Each line in this file is the name of a binary module to include in the library. The contents of this file is ultimately passed to the librarian to build the library. Each file name ends in ".obj".
The scripts and files used to build firmware are:
Builds the firmware in this repository. Each source module is assembled or compiled, and the resulting relocatable binaries built into a temporary library. The binary of the STRT module is then linked against this library to build the complete firmware. When successful, a .hex file results. For the 16 bit parts, a .elf file is also produced, and for the 8 bit parts a .cod file. The .elf or .cod files are necessary for debugging the firmware in MPLAB.
The build_fw script is called from the top level build script, but is also intended to be run directly by the user.
Grabs the dependency files required by the firmware source modules. These are put in the expected places in the <embed>\src tree where the source code of the firmware modules reference them.
This script is intended to be run from other build scripts, not directly by the user. It may have side effects, like changing the working directory and setting environment variables that should exist only during a build.
build_fwinit calls build_vars.
Modules list file. Each line in this file is a command to the librarian to include a particular binary module in the temporary library. The contents of this file is ultimately passed to the librarian to build the library. The format of each line is:
ADDMOD <module>.o
Version number file. This file contains the number of the current firmware version being built. The version is incremented by one by the picversion script, which releases the latest build of the current version and advances to the next version.
Sequence number file for version N. The sequence number starts at 1 for each version, and is then incremented by 1 each build. This guarantees that no two builds result in the same version and sequence number combination.