ACE/docs/msvc_notes.txt

   1
   2 /**
   3
   4 @page msvc Miscellaneous Notes for ACE/TAO and Microsoft Visual C++
   5
   6 Here are just some random information about ACE/TAO with Microsoft Visual
   7 C++.  This is more a collection of ideas right now, so it may not be as
   8 polished as other ACE documentation.
   9
  10 @subsection msvc_configurations Configurations
  11
  12 MSVC workspace and solution files come with several configurations.  The
  13 main two are Debug and Release.  Debug produces libraries and
  14 executables with debugging symbols and doesn't enable inlining.  The
  15 Release configuration enables optimizations and leaves out debugging
  16 symbols.  All projects contain both configurations. If you want to
  17 build static or mfc versions of the library you need to use different
  18 project and solution files. Project files with _Static extension
  19 denote workspaces for building static libraries.
  20
  21 Different configurations produce different libraries and executables.  For
  22 example, Debug versions of dynamic libraries are always named *d.dll (like
  23 aced.dll) and the executables are placed in the current directory.  Release
  24 versions of dynamic libraries are named *.dll (such as ace.dll) and their
  25 executables are usually placed in the Release subdirectory.  Other common
  26 suffixes include *sd.lib for Static Debug and *s.lib for Static Release.
  27
  28 Projects only use the same configuration versions of the libraries.  The Debug
  29 version of an ACE example only uses debug version of ACE library.
  30
  31 @subsection msvc_otheroptions How to Set Other Options
  32
  33 Other compile time options are set or unset via the config.h file.  For
  34 example, to turn on a compile time definition, #define it at the beginning of
  35 config.h.  Unsetting a definition just requires #define ACE_FOO 0 or a #undef
  36 at the end of the file (after including config-win32.h).  Different macros
  37 require different techniques.
  38
  39 @subsection msvc_libraries ACE/TAO Libraries
  40
  41 I don't think we have any documents really giving any info on what libraries
  42 are produced by the MSVC project files.
  43
  44 So unlike the Unix platforms, Win32 libraries do not have a prefix of "lib",
  45 instead it is used as an extension.  For example, the debug version of the
  46 dynamic ace library is aced.lib (which is a stub for aced.dll).  The three
  47 ACE libraries are:
  48
  49 - ace
  50 - ACE_RMCast
  51 - ACE_SSL
  52 - ACE_TMCast
  53
  54 And for TAO we have the main TAO library and several sub libraries which
  55 contain extra features of TAO that aren't always needed (such as the POA
  56 in TAO_PortableServer).
  57
  58 And finally we have the orbsvcs libraries.  Each ORB service is contained
  59 in its own library.  More libraries may be needed to be linked in, since
  60 some services require the use of others (such as TAO_AV requiring
  61 TAO_CosTrading and TAO_CosProperty).
  62
  63 The *.lib and *.dll files are located in ACE_wrappers/lib.  You need
  64 to point your PATH to $ACE_ROOT/lib for running the applications.
  65
  66 I hesitate to put down explicit instructions on what libraries need to be
  67 linked in, considering that the libraries are being split apart more and more
  68 for footprint purposes.  For most ACE stuff, you will only need to link in
  69 ace.lib.  For plain TAO clients TAO.lib is enough.  TAO servers also require
  70 TAO_PortableServer.lib for the POA.  If the TAO application uses Dynamic Anys,
  71 TAO_DynamicAny.lib is also needed.  Then if any of the ORB Services are used,
  72 more libraries are needed.  For example, a client that uses the Name Service
  73 would need to link TAO_CosNaming.lib.
  74
  75 And note that the release versions of the libraries are listed above.  For
  76 debug configurations the libraries would be aced.lib, TAOd.lib, etc.
  77
  78 @subsection msvc_external_projects External ACE/TAO Projects
  79
  80 It is a little difficult for us to list how exactly one should create
  81 projects that use ACE/TAO but are external to the ACE_wrappers tree.  Since
  82 most projects we create are in that tree, we can make assumptions about
  83 directory structure that doesn't always apply for external projects.  In
  84 other words, we have ideas how they should work, but they usually remain
  85 a bit, um, untested. :-)
  86
  87 There are three main dependencies a project would have on ACE/TAO.
  88
  89 - Include paths:  Since all the headers use a subdirectory way of referring
  90   to include files (such as "ace/OS.h" instead of just "OS.h").  In order
  91   to make this work either the path to ACE_wrappers (and ACE_wrappers\TAO and
  92   ACE_wrappers\TAO\orbsvcs, etc.) to the additional include paths of the
  93   project or in MSVC.  I believe it is a better idea to add them to the global
  94   MSVC directories.  That way the path to ACE on a machine doesn't get hard
  95   coded into the project itself (this should make it easier to move the
  96   project between machines where ACE is installed in different places).
  97
  98 - Libraries and library paths:  Depending on what features are needed,
  99   different libraries are needed to be linked in.  (This is covered more in
 100   an above section).  These libraries are specified in the project, but can
 101   be specified in different ways.  The first is the hard coded way (a full
 102   path, such as "C:\ACE_wrappers\ace\aced.lib").  The second is listing only
 103   the library (such as "aced.lib") and then specify the path either in the
 104   project or via MSVC global settings.  Just like for the include paths, MSVC
 105   global settings is probably the more robust way of specifying this.
 106
 107 - TAO_IDL: TAO's IDL compiler resides in ACE_wrappers\bin.  If the external
 108   project contains IDL files, then a custom build configuration can be used
 109   to automatically call TAO_IDL.  Note that the location of the release
 110   version of the compiler is in ACE_wrappers\bin\Release (although it doesn't
 111   matter which version you use, they both produce the same output).  If
 112   ACE_wrappers\bin is included in the path, then the build command can just
 113   refer to tao_idl and it can be found via the path.  The other options are
 114   to refer to tao_idl via an absolute hard coded path or to add
 115   ACE_wrappers\bin to the MSVC's global executable path settings.  Either
 116   way the bin directory must be in the path or in the global settings so
 117   tao_idl can find aced.dll.
 118
 119 So I guess in summary we would recommend adding most of the settings to Visual
 120 C++'s global settings (include paths, library paths, and executable paths)
 121 and just refer to the libraries without any paths.
 122
 123 @subsection msvc_aceroot ACE_ROOT
 124
 125 ACE_ROOT is an interesting environment variable.  Even though it is heavily
 126 used on Unix (in fact, ACE/TAO will not compile without it) it really isn't
 127 needed for MSVC.  The reason for this is that we were interested in making
 128 configuration and setup really easy for Visual C++ on Windows. In retrospect
 129 it might have made quite a few things easier to specify if ACE_ROOT was
 130 required.  One thing you might notice is that TAO_IDL will display a message
 131 if ACE_ROOT isn't set, but it is only a problem if the IDL file includes
 132 <orb.idl> and you don't use -I to specify where orb.idl is.
 133
 134 */