WARNING: THIS FILE IS OLD
=========================

Some of the information in this file is likely to be out of date.  It has not been
updated since 2005, so things like the minimum required versions are now wrong.


Compiling EPICS and Building IOC Applications on MS Windows 
-----------------------------------------------------------

Original port of EPICS base build system to Windows was done by Kay-Uwe Kasemir 11/96

Please mail questions, comments, corrections, additional examples, etc to Jeff Hill 
    at johill###at###lanl.gov (replace ###at### with @ of course)

0) what you will get
--------------------

This port of EPICS to windows allows you to build for two host architectures:

win32-x86 -  This is the native port to windows. Probably faster, more efficent, and with
             more precise time stamps. The OS dependent layers are carefully optimized 
             for EPICS. There is prioritized schedualing of threads. 
             
cygwin-x86 - This is the POSIX port of EPICS layered onto cygwin which is layered again
             onto win32. We have less experience with this version, but it is in use. I
             suspect that Mark Rivers has the most experience with it.  Mutexes may be
             slower, and time stamps are probably less precise. There were problems with 
             interrupting blocking system calls during cleanup in past version that may 
             be resolved in more recent versions of cygwin.

Once you have completed a host and or target build you can run all of the base components on
windows. This includes the client library (ca.dll, Com.dll), soft IOCs, portable server etc.

1) what you will need
---------------------

Depending on how you set the EPICS_HOST ARCH environment variable, you will need

o win32-x86 - MS Visual C/C++ (probably version 6 is the earliest version that can be used)
                (I understand that there are also available free versions of this compiler) 
o win32-x86-borland - Borland C free compiler and linker (I use Borland C++ 5.5.1 successfuly)
o win32-x86-mingw - MingW standalone GNU developers tools www.mingw.org
o win32-x86-cygwin - Cygwin hosted developers tools www.cygwin.com
o cigwin-x86 - Cygwin hosted developers tools targeting Cygwin GNU based posix www.cygwin.com

You can also cross compiler for Tornado (and possibly RTEMS) if you have it (them) installed on 
Windows. To build only for win32-x86 and not cross compile for IOC development type 
"make win32-x86" or in your configure/CONFIG_SITE file set "CROSS_COMPILER_HOST_ARCHS="

And some tools:
	gnu make - www.gnu.org (need 3.78.1 or later)
	perl - www.perl.org (need 5.0 or later)

The gnu make and perl executables are also downloadable from www.cygwin.com

The perl interpreter and gnu make are also available 'on the net'
as sources which compile with MS Visual C++.

2) set environment variables

(Setting env. vars. is different: for NT/W2K/WXP, use Settings/System,
for Win95 use autoexec.bat)

When setting paths in the EPICS CONFIG files for win32-x86 the following
are hints in case you have trouble. You should not need to worry about 
this unless you type a path into one of the EPICS config files that 
includes a "\". In most situations gnu make, windows NT/W2K/WXP, the MS compiler,
and the MS linker will accept "/" and this will result in less trouble.

	** Note that that each "\" in any path variables you set
		must be replaced with a "\\" (this is because GNU make treats
		all "\" characters as line continuation)

	*and* Note that that each space in any file name or 
        path name variable you set must be replaced with 
        a "\ " (this is because GNU make treats all " " separated
        input as independent tokens in the input stream.

	** win32-x86 will generally allow "/" and "\" interchangeably in file paths,
		but the DOS shell only accepts "\".

    ** Certain command line utilities such as the MS linker are known to in rare
        situations confuse "/" in a path with command line options, and it may
        be necessary to replace a "/" in a path that configured with "\\", but
        the bulk of our experience indicates that this is not the necessary.

Your path should include (in additon to ms system directories):
- The ms system directories
- The EPICS-binaries we are building <EPICS>base/bin/win32-x86 
        (really where INSTALL_LOCATION specifies)
- The developer tool set binaries
- perl
- GNU make

Check with e.g.: echo %Path%

On NT/W2K/XP, "Path" is defined by the operating system, on Win95, it's "PATH" instead.

Of course, Tornado should be installed properly with these env. variables set:

WIND_BASE=c:\Tornado		(required for cross development only)
WIND_HOST_TYPE=x86-win32	(required for cross development only)

This way the EPICS makesystem can locate Tornado without any changes to the files 
in base/config. So for pc486 the settings in CONFIG_SITE where you specify the 
location of VxWorks are ignored, this information is taken from WIND_BASE and 
_HOST_TYPE!!

If building with MSVC one ususally runs one of the following from a .cmd file:
call "c:\program files\Microsoft Visual Studio\VC98\Bin\Vcvars32.bat"
call "C:\Program Files\Microsoft Visual Studio .NET\Vc7\bin\Vcvars32.bat"
call "C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\bin\Vcvars32.bat"

The EPICS build system requires EPICS_HOST_ARCH environment variable
Select host arch to build:
	EPICS_HOST_ARCH=win32-x86
	EPICS_HOST_ARCH=win32-x86-borland 
	EPICS_HOST_ARCH=win32-x86-mingw
	EPICS_HOST_ARCH=win32-x86-cygwin
	EPICS_HOST_ARCH=cygwin-x86

Set the "TMP" environment variable if you need to specify where 
temporary files are created.

Directory Used For Temporary Files   Conditions
----------------------------------   ----------
Directory specified by TMP           TMP environment variable is set, 
                                     and directory specified by TMP exists.	
dir argument to _tempnam             TMP environment variable is not set, or 
                                     directory specified by TMP does not exist.	
P_tmpdir in STDIO.H                  dir argument is NULL, or dir is name of 
                                     nonexistent directory.	
Current working directory            P_tmpdir does not exist.	

On my system I see in stdio.h that _P_tmpdir is "/". Here is a common
setting for "TMP" (the C:\TEMP directory must exist).

TMP=C:\TEMP

3) building EPICS
-----------------

Prepare apx. 2 ltr. Tee and type:

	cd <epics>/base
	make 			(use gnu make)

Watch for errors and send them to me.

Known problems:
* Sometimes there are clock synchronization problems when mounting UNIX
file systems onto windows which results in warnings/errors like
  "file has modification date in the future"
  for newly created things.
  Very seldom this is fatal, so you have to
  stop gnumake and restart it.

4) Creating EPICS IOC applications under win32-x86

o create application development folder
	
o start a DOS window and change your working directory to the folder
	created above (with the DOS "cd" command)

o to create an example application type:
	"perl c:\epics\bin\win32\makeBaseApp.pl -b c:\\epics -e

	** Note that that each "\" above in any path arguments to makeBaseApp.pl
		must be replaced with a "\\" (this is because GNU make treats
		all "\" characters as line continuation)

	** Note that that each space in any file name or 
        path name argument to makeBaseApp.pl must be replaced with 
        a "\ " (this is because GNU make treats all " " separated
        input as independent tokens in the input stream.

	** Note that c:\epics above must be replaced by the path
		to your epics source installation (or where INSTALL_LOCATION 
		specifies)

o General information on EPICS IOC application development can be found in
	the "EPICS IOC Application Developers Guide". To see all of the options 
	supported by makeBaseApp.pl type "perl c:\epics\bin\win32\makeBaseApp.pl"

5) EPICS GNU make makefiles can be executed from within a Visual C++ "makefile"
style project. This allows EPICS programs to be developed directly inside of
the visual C++ environment. To do this create a "makefile" project and place your 
gnu make command in the build configuration (accessed from the project/settings menu). 
You will also need to add GNU make and <EPICS>/bin/win32 into the Visual C++ 
executable search path (from the tools/options menu). 
In visual C++ it is possible to double click on the compiler 
error messages generated within an EPICS "makefile" style project and have visual 
C++ immediately position the cursor on the corresponding line in the source. I
have found that this works correctly with Makefile projects if the project is in a 
directory just below the source code. The following build command works well
in a visual C++ make file project: "kill caRepeater.exe&make -C ..". Be careful 
not to introduce additional spaces around the &. The kill.exe command is in the
NT resource kit.

6) Issues that you should be aware of if you are building code with MSVC that 
calls EPICS, but you are not using the EPICS build system.

6a) You will need to include header files from the following paths.
    <epics>\base\include
    <epics>\base\include\os\win32
6b) You will need to link with the following path in effect.
    <epics>\base\lib\win32-x86. 
6c) If the visual C++ /Za option is not used then you will also need to define 
    __STDC__ to be zero on the command line so that EPICS headers will know that
    a ANSI standard C compiler is in use. 
6d) If you link with EPICS object libraries then specify /MT or /MTd
    depending on whether EPICS base and your code are built for debugging. 
    This specifies the multithreaded operating environment required by EPICS.
    This will also not define _DLL and therefore the EPICS header files will
    not specify that sharable libraries are being called. EPICS object library 
    names follow the convention "xxxObj.lib".
6e) If you link with EPICS shareable libraries (with DLLs) then you must 
    use /MDd or /MD depending on whether EPICS base and your code are 
    built for debugging. This specifies the multithreaded operating environment 
    required by EPICS. This will also define _DLL and therefore the EPICS header 
    files will specify an optimized calling convention for shareable libraries. 
    EPICS shareable libraries (DLL) names follow the convention "xxx.lib"
    and "xxx.dll".
