Mklib

The Run-time Support Library (RTS) source code is provided in each compiler release to allow the user to build an RTS library as needed.

There are an exponentially large number of distinct option sets which could be used to build the library, and it would be prohibitively expensive in terms of download size to create a compiler release that included all possible libraries. To provide maximum flexibility, the RTS source code is provided as part of each compiler release. To allow for quicker compiler release downloads, compiler releases pre-build only a small number of very commonly-used libraries. The missing libraries can be built by the user as desired. The linker can also automatically build missing libraries without additional effort from the user.

This is accomplished with a new library build process, the core of which is the executable mklib, which is available beginning with CCS 5.1

Required Texas Instruments Software

You must have a complete copy of the Texas Instruments compiler installed, including the compiler, linker, and archiver. You must be using at least a certain version of the tools:

ISA	version
C2000	6.0.2
C5500	4.4.0B1
C6000	7.3.0B3
ARM	4.9.1
MSP430	4.0.0B1

If you are able to compile and link programs, you should be able to build libraries.

If you are using the compiler tools from the command line, you either need to have the compiler tools in your PATH, or you must invoke the compiler tools with an absolute pathname. You must also either set the appropriate C_DIR environment variable (e.g. C6X_C_DIR) or you must specify the full pathname of libc.a on your linker command line or in the linker command file.

Required non-Texas Instruments Software

To use the self-contained run-time support build process, the following programs are required:

• sh (Bourne shell)
• unzip (InfoZIP unzip 5.51 or later, or equivalent)

http://www.info-zip.org

• gmake (GNU make 3.81 or later)

More information is available from GNU at http://www.gnu.org/software/make. This file requires a host C compiler to build. GNU make (gmake) is also available in earlier versions of CCS. GNU make is also included in some Unix support packages for Windows, such as the MKS Toolkit, Cygwin, and Interix. The GNU make used on Windows platforms should explicitly report "This program build for Windows32" when the following is executed from the Command Prompt window:

gmake -h

All three of these programs are provided as a non-optional feature of CCS 5.1. They are also available as part of the optional XDC Tools feature if you are using an earlier version of CCS.

mklib will look for these executables in the following order:

1. in your PATH
2. in the directory getenv("CCS_UTILS_DIR")/cygwin
3. in the directory getenv("CCS_UTILS_DIR")/bin
4. in the directory getenv("XDCROOT")
5. in the directory getenv("XDCROOT")/bin

If you are invoking mklib from the command line, and these executables are not in your PATH, you must set the environment variable CCS_UTILS_DIR such that getenv("CCS_UTILS_DIR")/bin contains the correct programs.

Using mklib

You should normally let the linker automatically rebuild libraries as needed. If necessary, you can run mklib directly to populate libraries. See below for situations when you might want to do this.

Automatic standard library rebuilding by the linker

The linker looks for RTS libraries primarily through the C6X_C_DIR environment variable (using the variable appropriate for your target). Typically, one of the pathnames in C6X_C_DIR is <your install directory>/lib, which contains all of the pre-built libraries, as well as the index library libc.a. The linker will look in C6X_C_DIR to find a library that is the best match for the build attributes of the application. The build attributes are set indirectly according to the command-line options used to build the application. Build attributes include things like CPU revision. If the library is explicitly named (e.g. rts6200.lib), RTS will look for that library exactly; otherwise, it will use the index library libc.a to pick an appropriate library.

The index library describes a set of libraries with different build attributes. The linker will compare the build attributes for each potential library with the build attributes of the application and will pick the best fit.

Now that the linker has decided which library will be used, it checks whether the RTS library is present in C6X_C_DIR. The library must be in exactly the same directory as the index library libc.a. If the library is not present, the linker will will invoke mklib to build it. This happens when the library is missing, regardless of whether the user specified the name of the library directly or allowed the linker to pick the best library from the index library.

mklib will build the requested library and place it in 'lib' directory part of C6X_C_DIR in the same directory as the index library, so it will be available for subsequent compilations.

Things to watch out for:

• The linker will invoke mklib and wait for it to finish before finishing the link, so users will experience a one-time delay when an uncommonly-used library is built for the first time. Build times of 1-5 minutes have been observed. This will depend on the power of the host (number of CPUs, etc).
• In a shared installation, where an installation of the compiler is shared among more than one user, it is possible that two users might cause the linker to rebuild the same library at the same time. mklib tries to minimize the race condition, but it is possible one build will corrupt the other. In a shared environment, all libraries which might be needed should be built at install time; see below for instructions on invoking mklib directly to avoid this problem.
• The index library must exist, or the linker will be unable to rebuild libraries automatically.
• The index library must be in a user-writable directory, or the library will not be built. If the compiler installation must be installed read-only (a good practice for shared installation), any missing libraries must be built at installation time by invoking mklib directly.
• The program mklib is specific to a certain version of a certain library; you cannot use one compiler version's RTS's mklib to build a different compiler version's RTS library.

Invoking mklib manually

The user may need to invoke mklib directly in special circumstances:

• The compiler installation directory is read-only or shared
• The user wants to build a variant of the RTS library that is not pre-configured in the index library libc.a or known to mklib. (e.g. a variant with source-level debugging turned on.)
• The user is having other build problems that require a manual build

Before invoking mklib manually, make sure that the path to the compiler tools \bin folder is added to your PATH.

Building standard libraries

Users can invoke mklib directly to build any or all of the libraries indexed in the index library libc.a. The libraries will be built with the standard options for that library; the library names and the appropriate standard option sets are known to mklib.

This is most easily done by changing the working directory to be the compiler RTS library directory 'lib' and invoking the mklib executable there:

mklib --pattern=rts6200.lib

Shared or read-only library directory

If the compiler tools are to be installed in shared or read-only directory, mklib cannot build the standard libraries at link time; the libraries must be built before the library directory is made shared or read-only. Also, if there are other problems with automatic link-time building of libraries, you can build all of the libraries manually to avoid automatic builds.

At installation time, the installing user must build all of the libraries which will be used by any user. To build all possible libraries, change the working directory to be the compiler RTS library directory 'lib' and invoke the mklib executable there:

mklib --all

Some targets (C6000 and TMS470) have many libraries, so this step can take a long time. To build a subset of the libraries, invoke mklib individually for each desired library.

Building libraries with custom options

The user can build a library with any extra custom options desired. This is useful for building a debugging version of the library, or with silicon exception workarounds enabled. The generated library is not a standard library, and must not be placed in the 'lib' directory. It should be placed in a directory local to the project which needs it. To build a debugging version of the library rts6200.lib, change the working directory to the 'lib' directory and run the command

mklib --pattern=rts6200.lib --name=rts6200_debug.lib --install_to=$Project/Debug --extra_options="-g"

Mklib option summary

Run the following command to see the full list of options.

mklib --help

    --index=FILENAME

                        The index library (libc.a) for this release.  Used to
                        find a template library for custom builds, and to find
                        the source files (rtssrc.zip).  REQUIRED.

    --pattern=FILENAME

                        Pattern for building a library.  If neither
                        --extra_options nor --options are specified, the
                        library will be the standard library with the standard
                        options for that library.  If either --extra_options
                        or --options are specified, the library is a custom
                        library with custom options.  REQUIRED unless --all is
                        used.

    --all

                        Build all standard libraries at once.

    --install_to=DIRECTORY

                        The directory into which to write the library.  For a
                        standard library, this defaults to the same directory
                        as the index library (libc.a).  For a custom library,
                        this option is REQUIRED.

    --compiler_bin_dir=DIRECTORY

                        The directory where the compiler executables are.
                        When invoking mklib directly, the executables should
                        be in the PATH, but if they are not, this option must
                        be used to tell mklib where they are.  This option is
                        primarily for use when mklib is invoked by the linker.

    --name=FILENAME

                        File name for the library with no directory part.
                        Only useful for custom libraries.


    --options='STR'

                        Options to use when building the library.  The default
                        options (see below) are REPLACED by this string.  If
                        this option is used, the library will be a custom
                        library.

    --extra_options='STR'

                        Options to use when building the library.  The default
                        options (see below) are also used.  If this option is
                        used, the library will be a custom library.

    --list_libraries

                        List the libraries this script is capable of building
                        and exit.  ordinary system-specific directory.

    --log=FILENAME

                        Save the build log as FILENAME

    --tmpdir=DIRECTORY

                        Use DIRECTORY for scratch space instead of the
                        ordinary system-specific directory.

    --gmake=FILENAME    Gmake-compatible program to invoke instead of "gmake"
    --parallel=N        Compile N files at once ("gmake -j N")

    --query=FILENAME    Does this script know how to build FILENAME?

    --help|h        Display this help
    --quiet|q       Operate silently
    --verbose|v     Extra information to debug this executable
 Examples:

    To build all standard libraries and place them in the compiler's
    library directory:

    mklib --all --index=$C_DIR/lib

    To build one standard library and place it in the compiler's library
    directory:

    mklib --pattern=rts6200.lib --index=$C_DIR/lib

    To build a custom library that is just like rts6200.lib, but has symbolic
    debugging support enabled:

    mklib --pattern=rts6200.lib --extra_options="-g" --index=$C_DIR/lib --install_to=$Project/Debug --name=rts6200_debug.lib

Extending mklib

The mklib API is a uniform interface which allows CCS to build libraries without needing to know exactly what underlying mechanism is used to build it. Each library vendor (e.g. the TI compiler) provides a library-specific copy of 'mklib' in the library directory which can be invoked which understands a standardized set of options, and understands how to build the library. This allows the linker to automatically build application-compatible versions of any vendor's library without needing to register the library in advance, as long as the vendor supports mklib.

Underlying mechanism

The underlying mechanism can be anything the vendor desires. For the compiler RTS libraries, mklib is just a wrapper which knows how to unpack Makefile from rtssrc.zip and invoke gmake with the appropriate options to build each library. If necessary, mklib can be bypassed and Makefile used directly, but this mode of operation is not supported by TI, and the user is responsible for any changes to Makefile. The format of the Makefile and the interface between mklib and the Makefile is subject to change without notice. mklib is the forward-compatible path.

Libraries from other vendors

Any vendor who wishes to distribute a library which can be rebuilt automatically by the linker must provide:

• an index library (like 'libc.a', but with a different name),
• a copy of mklib specific to that library, and
• a copy of the library source code (in whatever format is convenient).

These things must be placed together in one directory which is part of the linker's library search path (specified either in C6X_C_DIR or with the linker --search_path option).

If mklib needs extra information that is not possible to pass as command-line options to the compiler, the vendor will need to provide some other means of discovering the information (such as a configuration file written by a wizard run from inside CCS).

The vendor-supplied mklib must at least accept all of the above options without error, even if they don't do anything.

Troubleshooting

"CreateProcess ... ar470 ... failed"

This is probably known bug SDSCM00042061. The last step in building the library is to run the archiver command (e.g. "ar470"). In the test case for SDSCM00042061, the command line length of the ar470 command exceeded 32766 characters, which is the insurmountable upper limit of the Win32 API CreateProcess. See the defect entry for affected compiler versions.

If you are suffering from SDSCM00042061, the error message you will see is:

process_begin: CreateProcess(c:\progra~1\texasi~1\tms470~2.1\bin\ar470.exe,
c:/progra~1/texasi~1/tms470~2.1/bin/ar470 -qa
c:/docume~1/user.name/locals~1/temp/ti5b2e~1/rtsv7a8_a_le_eabi.lib
c:/docume~1/user.name/locals~1/temp/ti5b2e~1/obj/decode.obj
<over 500 object files listed here were deleted for clarity>
c:/docume~1/user.name/locals~1/temp/ti5b2e~1/obj/xatexit.obj, ...) failed.
make (e=87): The parameter is incorrect.

The workaround is to set your TEMP environment variable to something short, or to invoke mklib from the command line to create the library you need.

"CreateProcess ... cl470 ... failed. The system cannot find the file specified."

If you have quotation marks in the PATH environment variable, you will get an error that looks like this:

CreateProcess(NULL, cl470 atexit.c ...) failed.  The system cannot find the file specified.     

It is an error to have quotation marks in the PATH environment variable. Add search directories to PATH without quotes:

PATH=C:\Program Files\Texas Instruments\TMS470 4.9.1\bin;%PATH%

There is some indication that having an MKS toolkit directory in your %PATH% could cause this error. See the topic MKS or Cygwin or gmake tools in your path below.

"Could not create temp directory ... Invalid argument"

If you have quotation marks in the TEMP environment variable, you will get an error that looks like this:

>> ERROR: mklib: Could not create temp directory in c:/documents and settings/user.nam/tmp/"c:/docume~1/user.nam/locals~1/temp": Invalid argument

It is an error to have quotation marks in the TEMP environment variable. Set the TEMP environment variable without using quotes:

PATH=C:/Documents and Settings/user.nam/Local Settings/Temp

MKS or Cygwin or gmake tools in your path

Several users have reported problems using the library build utility in Windows when they have either some version of MKS Toolkit or Cygwin tools installed, or incompatible versions of sh.exe or gmake.exe in their PATH. The workaround is to remove these utilities from your PATH before running CCS or the compiler tools. What triggers this problem is presently unknown.

A quick way to find out if any of these utilities exist is to open a command prompt and search the path for the possibly problematic utilities

C:\> where sh

C:\> where cygwin

C:\> where gmake

Another source of problems related to sh.exe running Windows 10 may be Windows Defender. To work around the problem:

• Go to "Windows Defender Security Centre"
• Click on "App & Browser Control"
• At the bottom click on the "Exploit Protection Settings" link
• Go to "Program Settings" and click on the "Add program to customize" -> "Choose exact file path"
• Navigate to the location of sh.exe and add it
• Override and turn off the following: "Force randomization for images (Mandatory ASLR)", "Randomize memory allocations (Bottom-up ASLR)", "Validate stack integrity (StackPivot)"

General

If you are using CCS, make sure you have CCS 4.2.5 or above, or CCS 5.1 or above.

If you are running from the command line, make sure you have the compiler tools (cl470, ar470) and the support utilities (gmake, unzip, sh) in your PATH.

FAQ

Exactly which libraries will be pre-built?

The list of libraries will vary from release to release as libraries are determined to be commonly used. Look in the compiler release's 'lib' directory to see which libraries are pre-built for any particular release.

Will the names of the libraries change?

No.

What library should I choose when compiling my project?

Let the linker choose. Specify the index library 'libc.a', or make sure you use the "-c" or "-cr" linker option, and the linker will automatically pick the compiler RTS library that best matches the rest of your project.

How often will the library be rebuilt?

Just once per library, the first time it is needed.

Why not just download the library?

That would be nice, but it is not possible at this time.

What are the system requirements for building the library?

Aside from the general compiler requirements, 'mklib' requires the following to be in the user's path: the correct version of the TI compiler tools; a copy of GNU 'make' (or another make executable which supports GNU 'make' extensions); a copy of 'unzip' (InfoZIP unzip 5.51 or later); and a Bourne-compatible shell 'sh' which can support long command lines. All of these tools are available in XDCtools, which is already delivered as part of CCS.

Is there a risk that the compile might break?

It is possible, but unlikely. The user could tamper with the environment variables (e.g. 'C6X_C_DIR') or the host might not have enough resources, but things like that would have broken the link even if the libraries were shipped with the product. It is possible that the the build could fail if

• the library directory is read-only
• the user deleted or altered the contents of rtssrc.zip, libc.a, or mklib
• the temporary directory does not have enough free space to build a library

Will command-line users be forced to call mklib directly? Will old versions of CCS which do not understand mklib break?

No. The linker will attempt to call 'mklib' to rebuild a library if it can determine that some index file (e.g. libc.a) claims to index an appropriate library, but that library does not yet exist. This works best if users always choose "libc.a" as the RTS library instead of some more specific library.

What about users who don't use "libc.a", and instead refer to libraries by name (e.g. rts6200_eh.lib)?

As a special case, the linker will assume that if the requested library name matches one indexed by libc.a, then it really is the standard compiler RTS library with that name, and will proceed to build it. For this to be safe, users should not re-use the names of standard libraries for custom-built libraries.

Could the generated libraries have different performance and size characteristics?

No. The libraries are compiled internally with the same tool the user would use to build them. The user could choose to compile with different options, but that would be considered a "custom" library.

Will the standard libraries be compiled with "-g --optimize_with_debug"?

No.

Can I add my own standard libraries?

No. You can build an RTS library with whatever options you like, but it must not be paced in the compiler installation directory, or added to libc.a

Can I modify the compiler RTS source and recompile?

You can make a copy and do whatever you like with it, but you should not modify the copy in the compiler installation directory. The mklib library building process can survive trivial changes to the source files in rtssrc.zip (such as customizing the boot routine sequence), but adding and removing files might break the build. If you do modify the rtssrc.zip in the compiler installation directory, you must rebuild *all* of the existing libraries (or just delete them). If you modify rtssrc.zip, you are on your own. However, modifying the source code is an important use case, and a future stage of this project may support exporting to a new library project containing the source code for the compiler RTS, to which the user can make any desired modifications, leaving the original rtssrc.zip untouched. This modified source should not be installed in the compiler installation directory.

Can I modify the compiler RTS header files (e.g. stdio.h)?

You can make a copy and do whatever you like with it, but you should not modify the copy in the compiler installation directory. If you do modify the header files (such as changing the value of FOPEN_MAX) in the compiler installation directory, you must modify them both in the rtssrc.zip file and also in the include directory; mklib does not provide any mechanism for populating 'include' from the contents of rtssrc.zip. Furthermore, you must rebuild *all* of the existing libraries (or just delete them). If you modify the header files or rtssrc.zip, you are on your own. However, as in the previous question, modifying some values in header files is an important use case, and a future stage of this project may allow exporting to a new library project to make whatever changes are desired; in this case, the user needs to remember to modify the *_C_DIR environment variable to point to the modified header files.