revert 20523.
[reactos.git] / 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.