cocosetup – command line configuration tool

cocosetup is a program to automatically configure a compiler toolchain.

It can detect toolchains (compiler, linker, archive tool, and possibly more) in a directory, test the abilities of the tools and create wrappers for them.

Syntax

cocosetup <toolchain dir> [-c <toolchain>]... -o <output dir>

cocosetup <toolchain dir> [-c <toolchain>]... --in-place

cocosetup <toolchain dir> [--update-in-place | --revert-in-place]

cocosetup <toolchain dir> --list-toolchains [--recursive]

cocosetup --list-configurations

cocosetup

Options

• <toolchain dir>: Directory that contains the toolchain binaries.

  This directory contains the compiler, linker, archiver and possibly other programs that are necessary for a compilation.

  When this parameter is used in connection with --list-toolchains, it can also refer to a directory which only has one or more subdirectories with toolchains in them.

• -c <toolchain> | --configure=<toolchain>: Specify a toolchain to configure.

  When one or more toolchains should be configured, they are specified with one or more -c <toolchain> options. The names of the options are those that occur in the output of the command

  cocosetup <toolchain dir> --list-toolchains

• -o <output dir> | --output=<output dir>: Specify the output directory

  The output directory is that directory in which the compiler wrappers and supporting files reside. The parameter <output dir> must be either the path to a writable directory or the path to a subdirectory of a writable directory which does not yet exists. (It will then be created by cocosetup.)

• --in-place: Create the wrapper files in place.

  With this option, the compiler wrappers are created in the directory in which originally the toolchain files resided.

  Before that happens, the original files and subdirectories of the toolchain directory are copied to a backup directory. If the original directory is named foo, the backup directory has the name foo.cocosetup and resides in the same directory as foo. This directory must therefore be writable.

  The backup directory is still used by the compiler wrappers in the original toolchain directory and therefore cannot be removed.

• --revert-in-place: Bring an in place configured directory back to its original state.

  With this option, cocosetup removes the content of an in place configured directory foo, moves the content of its backup directory foo.cocosetup to foo, and then removes the directory foo.cocosetup.

  If the toolchain directory was not configured in place, cocosetup reports an error and does nothing.

• --update-in-place: Update an in place configured toolchain directory.

  With this option, cocosetup runs the tests for the given toolchains again and generates new wrappers. The names of the toolchains to configure need not to be specified because they are contained in the file cocosetup.json in the toolchain directory. If the toolchain directory was not configured in place, cocosetup reports an error and does nothing.

  A reconfiguration is especially needed after a new version of Coco was installed.

• --list-toolchains: Print the discovered toolchains.

  Print a list of the possible toolchains that cocosetup has found in the selected directory. Each entry consists of the name of the toolchain (which is invented by cocosetup) and the tools of which it consists. The name of the toolchain can leter be used with the -c option.

• -r | --recursive: Search recursively for toolchains.

  This option is a modifier to --list-toolchains. With it, cocosetup searches not only in the specified toolchain directory and also in its subdirectories and their subdirectories and so on.

  The option is meant for complex toolchain software packages in which it is not immediately clear where in a deep directory tree the compiler and related programs actually reside.

• --list-configurations: List the configured toolchain directories.

  cocosetup keeps track which directories it has configured. With this option, they can be displayed.

Content of the output directory

The output directory is either the directory that was specified with the -o option or, in case of an in-place configuration, the original toolchain directory that now is modified. It contains:

• For each file foo that belongs to the toolchain, two compiler wrappers, foo and csfoo, together with a configuration file foo.cspro.

  (Under Windows, these files are foo.exe, csfoo.csexe and foo.cspro)

• A file cocosetup.json with data about the configured toolchain in a form that can be read by cocosetup.
• A log file, cocosetup.log, that contains detailed information about all tests and other operations that were done by cocosetup when it configured the toolchain.
• A file README.md with human-readable information about Coco and the configuration of this directory.

Interactive mode

If it runs in a terminal and no or not enough parameters are given, cocosetup enters its interactive mode, where it asks the user for the values of the missing parameters. If a parameter value was given on the command line, cocosetup still asks for this value, but in the question for it, the parameter becomes the default answer and can be selected by pressing the Enter key.

After selecting the missing options, cocosetup executes the same configuration task as it would have done if all these options were given on the command line.

Intended workflow for cocosetup in the non-interactive mode

The workflow for the obo-interactive use of cocosetup consists of two steps:

1. Use cocosetup to get a list of all toolchains in a toolchain directory.
2. Choose one or more toolchains and configure them with cocosetup.

Here we show how this is done in a concrete case with Cygwin under Windows as an example

Finding the toolchains

The toolchain binaries of Cygwin reside in C:\cygwin64\bin. The command to find all possible Cygwin toolchains is therefore

C:\Users\someone>cocosetup C:\cygwin64\bin --list-toolchains

and its output is

Toolchain             C, C++, Linker, Archiver
---------             ------------------------
gcc                   gcc.exe, g++.exe, g++.exe, ar.exe
x86_64-pc-cygwin-gcc  x86_64-pc-cygwin-gcc.exe, x86_64-pc-cygwin-g++.exe, x86_64-pc-cygwin-g++.exe, x86_64-pc-cygwin-gcc-ar.exe

The left column of the output shows that cocosetup has found two toolchains, which it has given the names gcc and x86_64-pc-cygwin-gcc. In the left column we can see the tools of which each toolchain consists. The tool g++.exe occurs twice because it is used both as C++ compiler and as linker.

Configuring one toolchain

Let us assume now that we have decided to configure the toolchain gcc and create wrappers for it in the directory c:\Users\someone\cygwin-wrappers. The command for it is then

C:\Users\someone>cocosetup C:\cygwin64\bin -c gcc -o C:\Users\someone\cygwin-wrappers

and its output is

Logging to c:\Users\someone\cygwin-wrappers\cocosetup.log

==== Checking toolchain gcc ====
Compile minimal program: success
Build minimal program: success
Link program: success
Link archive: success
Target OS: Windows
Malloc: supported
File API: CreateFileA()
Shared pointer namespace: <none>
Unique pointer namespace: <none>
atexit() function: atexit()
Performance clock: clock_gettime
Profile timer: rdtsc
Additional linker arguments: -ldl
Custom Setup: MS

==== Writing to c:\Users\someone\cygwin-wrappers ====
Wrote files gcc.exe, csgcc.exe and gcc.cspro
Wrote files g++.exe, csg++.exe and g++.cspro
Wrote files ar.exe, csar.exe and ar.cspro
Wrote file cocosetup.json
Wrote file README.md

==== Verifying the gcc wrapper parameters ====
Compile minimal program (instrumented): success
Build minimal program (instrumented): success
Link program (instrumented): success
Link archive (instrumented): success

The console output shows the automatic feature detections that were run by cocosetup, together with their results, then the files that were written to the output directory and finally the verification tests in which some of the feature detection tests are run again with the compiler wappers instead of the original tools.

This output is only a short summary of that what cocosetup did actually do when it ran the checks. There is also a log file, cocosetup.log, in the output directory that contains more details. The path to the log file is also given at the beginning of the console output.

Availability

cocosetup is not available in Coco builds for the following legacy operating systems:

• CentOS 7
• Debian 7
• Debian 9