TRAC Development

From DDCIDeos
Jump to navigationJump to search

This is how to setup a development and build environment for TRAC.

Dependencies

Environment

For Windows, a desk maintainer environment obtained by installing the score-trac-maintainer-tools package from category Deos-bundles is the recommended environment. See install for more. Component c3x4xsim requires a 32-bit Cygwin version to build and component skyeye cannot build in a Handies DESK. The recommended Cygwin is therefore the Greys DESK baseline.

README PC installation provides a detailed description of the necessary Cygwin installation (if you are not installing a DESK or need information about sizes and environment variables).

TRAC building requires a Bash shell (the top level build script checks that the expected tools are present).

SCORE native and ppc603e compilers must be installed manually for a non-desk maintainer environment. For Windows, e.g. build 287 from DDS-20150910 may be used (build 281 from DDS-20120822 is the classic tool compiler which has seen service for over a decade). If the two compilers are installed in different locations, then let SCOREHOME give the path of the SCORE native compiler and SCOREHOME_PPC603E give the path of the SCORE ppc603e compiler (as each score_use.sh would set it up).

Installing SCORE build 288 in an old baseline such as Greys may require a patch (if /SCORE/common/bin/dacs_private/set_errorlevel.exe does not exist). Locate a set_errorlevel.exe in any SCORE installation then patch as follows from a DESK bash prompt: 

 $ mkdir -p /SCORE/common/bin/dacs_private
 $ cp -p <path-to-set_errorlevel.exe> /SCORE/common/bin/dacs_private/

SCORE

Alternatively install a recent DDS that has SCORE native and ppc603e. It can be installed anywhere, and the remainder of this discussion assumes it is installed at C:\TOOL_COMP. Recommended is SCORE build 287. If using another build, replace '287' with that build below.

In a Windows cmd box define SCOREHOME as the path to SCORE_Build287\SCORE, e.g.: 

  set SCOREHOME=c:\TOOL_COMP\SCORE_Build287\SCORE

In a Cygwin environment define SCOREHOME similar, e.g. 

  SCOREHOME=/cygdrive/c/TOOL_COMP/SCORE_Build287/SCORE

DACS

The DACS Windows Native compiler is used to compile the Ada parts of the MLDs. Follow these steps to license and install the DACS Windows Native tool set.

Acquire a DACS license. Maintainers have access to a license file providing access to DACS at \\ddsbuild\DDCI_integration\dacs_all_demo.dat. The license expires at the end of January every year. See Flexnet_License#DACS_Licenses for instructions.

Install the DACS Windows Native compiler. Run 4.7.15b setup. When asked what to install, choose:

  • Graphical User Interface
  • Windows NT Native Compile System
  • PDF Documentation

Now follow the last part of README PC installation regarding updates to the DACS installation.

Checkout

Due to the fact that some MLD tests have very long file and directory names, it is important not to make the path name of TRAC_dev too long. It is recommended to place TRAC_dev in a directory such as "C:\ST" /cygdrive/c/ST) (2-3 chars).

Check out svnco using any svn client and run it from the directory where you want your TRAC_dev checkout to appear. Extra parameters can provide e.g. SVN credentials (if checking out as user scoretest); see script for examples. The primary reason for this script is to get commit time stamps on files (such as headers) that appear directly in the final build.

TRAC_dev is checked out issuing a command such as: 

    ./svnco.sh TRAC_dev

If working from /cygdrive/c/ST, a directory structure starting at /cygdrive/c/ST/TRAC_dev/branches/mainline results.

Build

It is the intention that any correct environment is equally well suited to make official builds.

Follow How-To-Make-a-TRAC-Release.txt. Work from a fresh check out (for consistent time stamps and avoid problems with less than perfect clean up procedures). It takes several hours to run the fullshow script.

Check that the build is successful. The output on the screen should end with "Build completed". Most build problems lead to a build.dif file.

So far nothing has changed outside your sandbox. Once you are satisfied with your build, it should be posted to the ftp server. The identification of the zip files to post is output by fullshow. You should follow the steps outlined in the "Post Development Distribution" section in Software Release Howto.

A Cygwin Bash console must be used to build TRAC. After setting up the environment as described above, you enter the build directory (e.g. /cygdrive/c/ST/TRAC_dev/branches/mainline/build) and issue: 

        ./fullshow

The fullshow script defaults to building all targets but can be called with the names of specific targets.

Tag TRAC_dev after posting a new release. Use svnsave to ensure proper handling of subcomponents.

MLD

To build just mld_<target>.exe, use a Windows cmd prompt. Note: this does not work if you launch a cmd prompt from within Cygwin; you gotta launch it from explorer, like with the Start Menu.

The fullshow script also builds all the needed MLDs, but if you as a TRAC maintainer wants to experiment with some of the MLD sources it is possible to make your source changes for a specific target, compile them individually, and then link a new MLD for this target. If you have no changes, but just want to rebuild (<target> e.g. native): 

cd C:\ST\TRAC_dev\branches\mainline\cmp\multi_language_debugger\build\NT\<target>
make_working_lib.bat & link_working_lib.bat

The directory structure: 

C:\ST\TRAC_dev\branches\mainline\cmp\multi_language_debugger\build\NT\release

will then be updated for the target in question, and the resulting mld[_<target>].exe file resides in ..\release\<target>\bin\. The fullshow script automatically updates this local release directory to TRAC's release directory: 

   C:\ST\TRAC_dev\branches\mainline\releases\winnt

The TRAC test system uses the MLDs from this structure for its testing.

If you make experiments with sources you must be aware of the fact that each target has a called files.list in which the exact set of sources needed for this target are recorded. From target to target a large portion of the individual files.list files are common, but each target typically have a specific set of files. If new files are added, this must be recorded in the files.list file(s) or they will not be compiled.

The most usual is that a problem is present in specific files, which then are updated. Since it is important that the proper compile switches are used the safe approach is to build use make_working_lib.bat and that saves the current Ada library (MLD source code is written in Ada83) and creates a new Ada library.

If you wish to save time and avoid the renamings, the arm target contains a script - arm\comp_single.bat - that is to be called with the source file you wish to compile, as it is specified in the local files.list (where it is a relative file name): 

  ..\arm\comp_single.bat ..\..\..\src\common_types\independent\ct_debugger_id_b.ada

if you have updated the build number in the above file. Please note that Ada does not allow you to compile source files in any order, so if you recompile an Ada specification, you invalidate all those other Ada units that depends on this specification. If done by mistake, building from scratch is the best solution.

After having compiled the set of changed sources, use link_working_lib.bat to create the MLD in the local release structure, and copy that to the TRAC release, possibly after having saved the previous version away.

Then test the effect of your change of this new MLD.

Testing

The tests are run from a Windows command prompt, starting from the tests directory (e.g. C:\ST\TRAC_dev\branches\mainline\cmp\multi_language_debugger\tests\main). There are two main test files: 

        r_423_461_530_all.bat (simulators)
        r_423_461_530_board.bat (boards)

Look at the files to see how to invoke them.

Test Environment

The test files run different compilers which must all be present. Baselines Denali/Elbert? (with GCC version 4.2.3), Greys (with GCC version 4.6.1) and Handies (with GCC version 5.3.0) DESKs must be installed. The default installation locations are C:\MLD-GCC-<gcc-version>, see e.g. test file r_423_461_530_all.bat for details.

Python 2.7 (32 bit version) must also be installed (using Python-2.7.18). The expected installation path is C:\Python27.

Run MLD outside OpenArbor

It is generally tricky to run MLD on Deos programs outside OpenArbor as the latter knows where to find the load list and how to select communication parameters. Normally OpenArbor starts the MLD command directly without any chance of user intervention but OpenArbor accepts a special option to accommodate this. This is useful both if you just want to modify the MLD invocation (e.g. to activate internal debug output) and if you want to debug MLD itself. Modify the OpenArbor shortcut on the desktop as follows:

  1. Right click the shortcut, select Properties.
  2. Click tab Shortcut.
  3. Append --testddci to the Destination field (right after OpenArbor.exe). Notice the double hyphen.
  4. Click OK. Note that this change will affect any MLD launch from this OpenArbor.

OpenArbor behaves as before until you right click on a process and select Debug with mld. A Launch MLD Dialog popup occurs.

  1. Click radio button Do not start an MLD.
  2. Copy the contents of the Command Line field up to and including the executable (do not copy options -guiipc, -guiip, -mldip, -guitomld and -mldtogui). Note that the entire line may not fit on your screen.
  3. Optionally click OK.
  4. Start MLD from a CMD console (launched from start menu, e.g. Windows System | Command Prompt in Windows 10 as I/O doesn't seem to work in DESK consoles). All paths on the copied command line are absolute so you can freely chose the work directory.

Note that test_options.txt describes how to activate debug output from within the MLDs, via the -TEST_OPTIONS option. The MLD has a concept of subsystems that may have the ability to output flow information. For each subsystem you can specify a set of characters (typically letters) and adding one or more for a subsystem will trigger the chosen ones. subsystems and options are separated by commas, and you may specify multiple sets, separating the sets with commas as well: e.g. GDB,DM,UIC,I.

Run Command Line MLD

Issue the copied command line from your CMD console: 

 $ <Command Line plus your options>

Debug MLD

Since all the MLDs are DACS Ada83 programs, debugging them requires using the DACS Ada83 debugger (c:\DACS\native\ad.exe) specifying the Ada library (working.alb) in the target directory, the name of the MLD main program (mld_main) and the invocation of the MLD with its parameters and options, so that the MLD when run under the DACS debugger, can execute as it did running 'stand-alone'. The -object "..." option for the DACS debugger can be used to do this. This is a bit cumbersome but possible to do. Assuming the DACS installation is in C:\DACS and the MLD to debug was built from C:\TRAC_dev\branches\mainline\cmp\multi_language_debugger\build\NT\arm\working.alb then this could be (from your CMD console): 

 $ C:\DACS\native\ad /lib C:\TRAC_dev\branches\mainline\cmp\multi_language_debugger\build\NT\arm\working.alb /object "Command Line plus your options" mld_main

Documentation

External

Lives in TRAC_Documentation. Making_TRAC_Documentation.txt contains notes on how to update and subsequently generate PDF and HTML files.

Internal

Very old MLD design documentation can be found in HCL Notes database SCORE Project Documents (for historic reasons).

The OpenArbor/MLD interface document is found in HCL Notes database SCORE Project Documents under GUI <-> Debugger Interface Document.

Retrieved from "https://ddci.zapto.org/ddciWiki/index.php?title=TRAC_Development&oldid=75449"