How to Set Up Host Code Build Environment

This document describes what to do after you've downloaded and installed an Embed Inc software release with host (as apposed to PIC or some other processor) source code, and you want to rebuild the software from that source code. 

Special thanks go to Xiaofan Chen for getting the environment set up on his system and adding to the checklist below. 

  1. Read the Structure of installed software section of the software installation instructions document.  This gives a good overview of what directories are supposed to contain what. 

  2. Make sure the Microsoft Visual C++ compiler is installed.  We use the last version Microsoft released before ending the subscription service back in the late 1990s.  Newer versions might work, but we wouldn't know.  The CL command reports version 12.00.8168, and the CD was labeled version 6.0. 

  3. Make sure a bunch of environment variables are properly set.  Here is a dump of the relevant environment variables from one of our systems, although the values will very likely need to be different on your system: 

    COGNIVIS=C:\embed
EmbedInc=C:\embed
include=c:\apps\msvc\include
lib_sys=c:\apps\msvc\lib
MSVCDir=c:\apps\msvc
Path=...   c:\apps\vstudio\common\msdev98\bin  ... 
temp=c:\temp
tmp=c:\temp

    COGNIVIS and EMBEDINC should have been created by the installation procedure.  Both should contain the pathname of where you installed the software to.  In the example above, the software installation directory was C:\embed.  The installation procedure should also have added the COM directory within the installation directory to the PATH variable. 

    MSVCDIR must contain the installation directory name of the Visual C++ compiler.  The compiler installation will put the Visual Studio part of the compiler in a different place.  The common\msdev98\bin directory within the Visual Studio installation directory must also be added to the command search path (PATH variable). 

    INCLUDE is the list of directories where system include files are stored.  It would usually contain the full name of the INCLUDE directory within the Visual C++ installation directory. 

    LIB_SYS is the list of directories where system libraries are stored.  You need not set LIB since it will be created each time when needed by the build scripts.  It will contain the complete list of directories to search for linkable library files.  This will be the list needed to find the Embed Inc libraries, which the build scripts know about, plus whatever you put in LIB_SYS. 

    TEMP and TMP should already be present on your system. 

    As another example, below are these environment variables on Xiaofan's system.  He also installed the PIC development environment, which requires MPLABDIR and DSPICDIR: 

    COGNIVIS=C:\embedinc
dsPICdir=C:\Program Files\Microchip\MPLAB ASM30 Suite
EMBEDINC=C:\embedinc
INCLUDE=C:\Program Files\Microsoft Visual Studio\VC98\include;.... 
lib_sys=C:\Program Files\Microsoft Visual Studio\VC98\lib
MPLABDIR=C:\Program Files\Microchip\MPASM Suite
MSVCDir=C:\Program Files\Microsoft Visual Studio\VC98
Path=C:\embedinc\com;C:\Program Files\Microsoft Visual Studio\VC98\bin; ... 
TEMP=C:\DOCUME~1\Test\LOCALS~1\Temp
TMP=C:\DOCUME~1\Test\LOCALS~1\Temp

  4. Make sure symbolic links are set up correctly.  Since true symbolic links are not always available on Windows systems, the Embed Inc software uses files with names that end in ".@".  All Embed Inc software will see these as symbolic links, although they will be ordinary files to Windows. 

    Symbolic links are manipulated with the SLINK command, and are shown with the directory list command L. 

    The only required symbolic link is COGNIVISION_LINKS in the system root directory ("/" using Embed Inc portable pathnames) pointing to the software installation directory ("(cog)" using Embed Inc portable pathnames).  This link should have been created by the software installation procedure.  You can verify this by running l /.  If the link is not present, you can create it by running the command slink /cognivision_links (cog). 

  5. Test the setup by running the build scripts.  All the build scripts are in the COM directory within the software installation directory, which is in the command search path.  This means they can be entered at the command line regardless of the current directory.  It is a good idea not to set the current directory to COM since some of the programs may have side effects, like creating temporary files.  COM should be kept clean to only contain executable files. 

    If you want to try the "big bang" test, try running build_base.  If that works, everything is fine and you've just rebuilt all the "base" libraries and utility programs. 

    If that doesn't work or you want to test things incrementally, follow these steps:

    1. Go to the EXAMPLES > SST directory (within the software installation directory.  By now we assume you know this.).  HELLO.PAS is the Pascal source for a simple program that just writes "Hello, world." to standard output.  Try running build_pas hello.  That should create HELLO.EXE, which you can run by entering hello. 

      If that doesn't work, you can decompose BUILD_PAS into smaller steps.  BUILD_PAS is a script, so running "doc build_pas" will display its contents.  You can see that the first thing BUILD_PAS does is to run COMPILE_PAS, which runs SST.  Try running SST directly for starters: sst hello.pas.  This should produce HELLO.C.  Once that is working, run compile_c hello which should produce HELLO.OBJ from HELLO.C.  Keep following the cookie crumbs in the BUILD_PAS script until you find out what the problem is and fix it.  Most likely one or more environment variables are not set up correctly. 

    2. Once BUILD_PAS works on the HELLO program, most things are probably set up correctly.  Now try building the lowest level library, which is called SYS.  The four "base" libraries, SYS, UTIL, STRING, and FILE, are required for just about any build of Embed Inc software.  Run build_sys_lib to rebuild the SYS library.  Again, follow the cookie crumbs in the scripts to figure out what doesn't work and fix it. 

    3. If the SYS library can be built, probably everything else can be too.  Run build_base and it will most likely work. 

  6. Try building whatever part of the software you are interested in.  For example, to build the PIC_PROG program run build_pic_prog_prog. 

Last Updated 21 January 2006