GetCPInfo should return FALSE if called with NULL info buffer.
[wine] / documentation / winelib-mfc.sgml
1   <chapter id="mfc">
2     <title id="mfc.title">Dealing with the MFC</title>
3
4     <sect1 id="mfc-introduction">
5       <title id="mfc-introduction.title">Introduction</title>
6       <para>
7         To use the MFC in a Winelib application you will first have to
8         recompile the MFC with Winelib. In theory it should be possible to
9         write a wrapper for the Windows MFC as described in
10         <xref linkend="bindlls" endterm="bindlls.title">. But in practice
11         it does not seem to be a realistic approach for the MFC:
12       </para>
13       <itemizedlist>
14         <listitem>
15           <para>
16             the huge number of APIs makes writing the wrapper a big task in
17             itself.
18           </para>
19         </listitem>
20         <listitem>
21           <para>
22             furthermore the MFC contain a huge number of APIs which are tricky
23             to deal with when making a wrapper.
24           </para>
25         </listitem>
26         <listitem>
27           <para>
28             even once you have written the wrapper you will need to modify
29             the MFC headers so that the compiler does not choke on them.
30           </para>
31         </listitem>
32         <listitem>
33           <para>
34             a big part of the MFC code is actually in your application in
35             the form of macros. This means even more of the MFC headers have
36             to actually work to in order for you to be able to compile an
37             MFC based application.
38           </para>
39         </listitem>
40       </itemizedlist>
41       <para>
42         This is why this guide includes a section dedicated to helping you
43         compile the MFC with Winelib.
44       </para>
45     </sect1>
46
47     <sect1 id="mfc-legal-issues">
48       <title id="mfc-legal-issues.title">Legal issues</title>
49       <para>
50         The purpose of this section is to make you aware of potential legal
51         problems. Be sure to read your licenses and to consult your lawyers.
52         In any case you should not consider the remainder of this section to
53         be authoritative since it has not been written by a lawyer.
54       </para>
55       <para>
56         During the compilation of your program, you will be combining code
57         from several sources: your code, Winelib code, Microsoft MFC code,
58         and possibly code from other vendor sources. As a result, you must
59         ensure that the licenses of all code sources are obeyed. What you are
60         allowed and not allowed to do can vary depending on how you combine
61         the code and if you will be distributing it. For example, if you
62         are releasing your code under the GPL or LGPL, you cannot use MFC
63         because these licenses do not allow covered code to depend on
64         libraries with non-compatible licenses.
65         There is a workaround - in the license for your
66         code you can make an exception for the MFC library.
67         For details see
68         <ulink url="http://www.gnu.org/licenses/gpl-faq.html">The GNU GPL FAQ</ulink>.
69       </para>
70       <para>
71         Wine/Winelib is distributed under the GNU Lesser General Public
72         License. See the license for restrictions on the modification and
73         distribution of Wine/Winelib code. In general it is possible to
74         satisfy these restrictions in any type of application.
75         On the other hand, MFC
76         is distributed under a very restrictive license and the restrictions
77         vary from version to version and between service packs. There are
78         basically three aspects you must be aware of when using the MFC.
79       </para>
80       <para>
81         First you must legally get MFC source code on your computer. The MFC
82         source code comes as a part of Visual Studio. The license for
83         Visual Studio implies it is a single product that can not
84         be broken up into its components. So the cleanest way to get MFC on
85         your system is to buy Visual Studio and install it on a dual boot
86         Linux box.
87       </para>
88       <para>
89         Then you must check that you are allowed to recompile MFC on a
90         non-Microsoft operating system! This varies with the version of MFC.
91         The MFC license from Visual Studio 6.0 reads in part:
92       </para>
93       <blockquote>
94         <para>
95           1.1 General License Grant. Microsoft grants to you as an
96           individual, a personal, nonexclusive license to make and use
97           copies of the SOFTWARE PRODUCT for the sole purposes of designing,
98           developing, and testing your software product(s) that are designed
99           to operate in conjunction with any Microsoft operating system
100           product. [Other unrelated stuff deleted.]
101         </para>
102       </blockquote>
103       <para>
104         So it appears you cannot even compile MFC for Winelib using this
105         license. Fortunately the Visual Studio 6.0 service pack 3 license
106         reads (the Visual Studio 5.0 license is similar):
107       </para>
108       <blockquote>
109         <para>
110           1.1 General License Grant. Microsoft grants to you as an
111           individual, a personal, nonexclusive license to make and use
112           copies of the SOFTWARE PRODUCT for the purpose of designing,
113           developing, and testing your software product(s). [Other unrelated
114           stuff deleted]
115         </para>
116       </blockquote>
117       <para>
118         So under this license it appears you can compile MFC for Winelib.
119       </para>
120       <para>
121         Finally you must check whether you have the right to distribute an
122         MFC library. Check the relevant section of the license on
123         <quote>redistributables and your redistribution rights</quote>. The
124         license seems to specify that you only have the right to distribute
125         binaries of the MFC library if it has no debug information and if
126         you distribute it with an application that provides significant
127         added functionality to the MFC library.
128         <!-- FIXME: quote relevant sections of EULA in above paragraph. -->
129       </para>
130     </sect1>
131
132     <sect1 id="mfc-compiling">
133       <title id="mfc-compiling.title">Compiling the MFC</title>
134       <para>
135         Here is a set of recommendations for getting the MFC compiled with
136         WineLib:
137       </para>
138       <para>
139         We recommend running winemaker in
140         '<option>--interactive</option>' mode to specify the right
141         options for the MFC and the ATL part (to get the include paths
142         right, to not consider the MFC MFC-based, and to get it to
143         build libraries, not executables).
144       </para>
145       <para>
146         Then when compiling it you will indeed need a number of
147         <literal>_AFX_NO_XXX</literal> macros. But this is not enough
148         and there are other things you will need to
149         '<literal>#ifdef</literal>-out'.  For instance Wine's richedit
150         support is not very good.  Here are the AFX options I use:
151       </para>
152       <para>
153         <programlisting>
154 #define _AFX_PORTABLE
155 #define _FORCENAMELESSUNION
156 #define _AFX_NO_DAO_SUPPORT
157 #define _AFX_NO_DHTML_SUPPORT
158 #define _AFX_NO_OLEDB_SUPPORT
159 #define _AFX_NO_RICHEDIT_SUPPORT
160         </programlisting>
161       </para>
162       <para>
163         You will also need custom ones for
164         <function>CMonikerFile</function>, <function>OleDB</function>,
165         <function>HtmlView</function>, ...
166       </para>
167       <para>
168         We recommend using Wine's msvcrt headers (<literal>-isystem
169         $(WINE_INCLUDE_ROOT)/msvcrt</literal>), though it means you
170         will have to temporarily disable winsock support
171         (<literal>#ifdef</literal> it out in
172         <filename>windows.h</filename>).
173       </para>
174       <para>
175         You should use g++ compiler more recent than g++ 2.95. g++
176         2.95 does not support unnamed structs while the more recent
177         ones do, and this helps a lot. Here are the options worth
178         mentioning:
179         <itemizedlist>
180           <listitem>
181             <para>
182               <literal>-fms-extensions</literal> (helps get more code
183               to compile)
184             </para>
185           </listitem>
186           <listitem>
187             <para>
188               <literal>-fshort-wchar -DWINE_UNICODE_NATIVE</literal>
189               (helps with Unicode support)
190             </para>
191           </listitem>
192           <listitem>
193             <para>
194               <literal>-DICOM_USE_COM_INTERFACE_ATTRIBUTE</literal>
195               (to get the COM code to work)
196             </para>
197           </listitem>
198         </itemizedlist>
199       </para>
200       <para>
201         When you first reach the link stage you will get a lot of
202         undefined symbol errors. To fix these you will need to go back
203         to the source and <literal>#ifdef</literal>-out more code
204         until you reach a 'closure'. There are also some files that
205         don't need to be compiled.
206       </para>
207       <para>
208         Maybe we will have ready-made makefile here someday...
209       </para>
210     </sect1>
211
212   </chapter>
213
214 <!-- Keep this comment at the end of the file
215 Local variables:
216 mode: sgml
217 sgml-parent-document:("winelib-user.sgml" "book" "chapter" "")
218 End:
219 -->