msvc6/README.txt

   1 ReactOS Microsoft Visual C/C++ 6.0 IDE files
   2
   3 This is the Microsoft Visual C/C++ 6.0 project workspace and project
   4 files for a few of the ReactOS binaries. They are ONLY included as a
   5 convenience, and is NOT to be considered supported, or even correct.
   6 If you build a binary that misbehaves using these files, you _might_
   7 be able to get in touch with someone to fix the problem
   8          BUT DO NOT COUNT ON IT!
   9
  10 The only supported build system for ReactOS is the one documented at
  11 www.reactos.com.
  12
  13 ------------------------------------------------------------------
  14 Please, before you start playing with this, read the whole of
  15 this document.
  16
  17 Before you can use these project files, you _need_ to make a successful
  18 build using the normal ReactOS build system. There are some vital files
  19 that needs to be created, and currently only the normal build creates these.
  20
  21 Once that is done, you need to generate the kernel-mode service "table"
  22 file by running nmake (from this point on you can use the "native"
  23 MSVC tools) from the directory MSVC6\iface\native.
  24 This will generate MSVC6\ntoskrnl\nt_zw_msvc.c, an MSVC compatible inline-
  25 assembler version of the file otherwise known as reactos\ntoskrnl\nt\zw.c.
  26
  27 Next, go to def_converter and run nmake. This builds the tool to convert
  28 the .def files for HAL and the kernel from the MinGW format to something
  29 more suitable for the MSVC linker, and also generates these .def files
  30 to their target location [1].
  31
  32 Now you should be set to fire up the IDE and load the project workspace.
  33
  34
  35 When building HAL or the kernel for the first time using these
  36 project files, just doing it the "normal" way _will not work_.
  37 The linker will complain about missing library, and it will fail.
  38
  39 The reason for this is a circular dependency between these two binaries.
  40
  41 Currently you need to follow these procedures [2]:
  42
  43 - Select hal as your active project.
  44 - Select Project/Settings.
  45 - Select the Link tab.
  46 - Select "General" from the Category drop-list.
  47 - Temporary remove the explicit linker library
  48   (e.g. "..\ntoskrnl\Debug\ntoskrnl.lib")
  49 - Select "Customize" from the Category drop-list.
  50 - Check the "Force file output" checkbox.
  51 - Build hal.
  52 - Uncheck "Force file output".
  53 - Put back the removed import library.
  54 - Now build the ntoskrnl. Do NOT try to build hal again until
  55   you have sucessfully built the kernel, and the linker has
  56   generated its import library!
  57 - Now you can "Clean" hal, and build it as usual.
  58
  59 If everything worked as expected, you should now have both ntoskrnl.exe
  60 and hal.dll freshly built.
  61
  62
  63 LIMITATIONS/DEVIATIONS (from the MinGW build):
  64 - Since there can only be one resource file/project, the kernel had
  65 to choose between either its version resource, or its message table.
  66 The messages won.
  67 - Do NOT open the .rc files in the IDE's resource editor. Chances are
  68 it will assume ownership over them and fill them up with at least
  69 conditional compilation macros.
  70
  71
  72 NOTES:
  73
  74 [1] This is needed due to differences in handling of decorated names
  75 in .def files. While both MinGW GCC and MSVC generates decorated names
  76 in the same way for at least plain cdecl and stdcall C functions, the
  77 MSVC linker expects names in the .def file to be either
  78
  79 - an exact match of the decorated name, in case it exports the
  80   decorated name from the linked binary, or
  81 - just the name without any decoration, in case it exports just the
  82   name of the symbol from the linked binary (to allow for e.g.
  83   GetProcAddress using the undecorated name) - but keeps the decorated
  84   names in the import library to handle and "redirect" linker requests
  85   for those decorated symbols, and point them to the undercorated names
  86   in the binary exporting them - so that a binary A, at link time,
  87   importing symbols from binary B of the form "_name@0" will resolve
  88   that symbol from the import library, but the linked binary A will
  89   reference it as just "name".
  90
  91 The ROS .def files contains a mix, "half-decorated", where the leading
  92 undescores are missing, but the trailing "@n" (for stdcall functions)
  93 are present.
  94
  95
  96 [2] Theoretically it could be possible to use a hal.lib generated by the
  97 following procedure, removing the need for the manual steps above.
  98
  99   cd MSVC6\hal\Debug
 100   lib \def:..\..\..\reactos\hal\hal\hal.def
 101
 102 but I have not tested it, and take no responsibility for its effectiveness.