Tom Kyer's DevCpp-Mingw Install & Compilation guide

2 files changed, 306 insertions, 4 deletions

diff --git a/docs/INSTALL.devcpp b/docs/INSTALL.devcpp
new file mode 100644
index 000000000..8ff4144cc
--- /dev/null
+++ b/docs/INSTALL.devcpp
@@ -0,0 +1,302 @@
+DevCpp-Mingw Install & Compilation                                   Sept 2005
+==================================
+
+Reference Emails available at curl@haxx.se: 
+
+  Libcurl Install and Use Issues
+  Awaiting an Answer for Win 32 Install 
+  res = curl_easy_perform(curl); Error
+  Makefile Issues
+  
+
+Having previously done a thorough review of what was available that met my
+requirements under GPL, I settled for Libcurl as the software of choice for
+many reasons not the least of which was the support.
+
+Background
+----------
+
+This quest started when I innocently tried to incorporate the libcurl library
+into my simple source code. I figured that a few easy steps would accomplish
+this without major headaches. I had no idea that I would be facing an almost
+insurmountable challenge.
+
+The main problem lies in two areas. First the bulk of support for libcurl
+exists for a Unix/linux command line environments. This is of little help when
+it comes to Windows O/S.
+
+Secondly the help that does exist for the Windows O/S focused around mingw
+thru a command line argument environment.
+
+You may ask "Why is this a problem?"
+
+I'm using a Windows O/S with DevCpp. For those of you who are unfamiliar with
+DevCpp, it is a window shell GUI that replaces the command line environment
+for gcc. A definite improvement that I am unwilling to give up. However using
+DevCpp presented its own set of issues. Inadvertently I also made some
+careless errors such as compiling the 7.14 version of Makefile with an older
+version of source code. Thanks to Dan Fandrich for picking this up.
+
+I did eventually with the help of Daniel, Phillipe and others manage to
+implement successfully (the only mingw available version)
+curl-7.13.0-win32-ssl-devel-mingw32 into the DevCpp environment. Only the
+dynamic libcurl.dll libcurldll.a libraries worked. The static library which I
+was interested in did not. Furthermore when I tried to implement one of the
+examples included with the curl package (get info.c) it caused the executable
+to crash. Tracing the bug I found it in the code and function res =
+curl_easy_perform(curl);.
+
+At this point I had to make a choice as to whether invest my limited
+time-energy resource to fixing the bug or to compile the new version
+available. After searching the archives I found a very similar or the same bug
+reported from version 7.12x on. Daniel did inform me that he thought that this
+bug had been fixed with the latest version. So I proceeded to compile the
+latest SSL version where I faced other challenges.
+
+In order to make this process unremarkable for others using the same
+environment I decided to document the process so that others will find it
+routine. It would be a shame if newbies could not implement this excellent
+package for their use.
+
+I would like to thank the many others in this forum and in the DevCpp forum
+for their help. Without your help I may either have given up or it would have
+taken me many times longer to achieve success.
+
+The Cookbook Approach
+---------------------
+
+This discussion will be confined to a SSL static library compilation and
+installation. Limited mention and comments will be inserted where appropriate
+to help with non-SSL, dynamic libraries and executables.
+
+
+   Using Makefile from DevCpp to compile Libcurl libraries
+
+Preamble
+--------
+
+Using the latest version release - curl-7.14.0.tar.gz. Curl source code is
+platform independent. This simply means that the source code can be compiled
+for any Operating System (Linux/Unix Windows etc. and variations of thereof).
+
+The first thing to note is that inside curl-7.14.0 you will find two folders
+lib and src. Both contain Makefile.m32 (required for win mingw library or exe
+compilation) files which are different. The main difference between these two
+folders and the makefiles is that the src folder contents are used to compile
+an executable file(curl.exe) while the lib folder contents are used to compile
+a static (libcurl.a) and dynamic (libcurl.dll & libcurldll.a) file that can be
+used to compile libcurl with your own source code so that one can use and
+access all libcurl functions.
+
+Before we start please make sure that DevCpp is installed properly. In
+particular make sure you have no spaces in the name of any of the directories
+and subdirectories where DevCpp is installed. Failure to comply with the
+install instructions may produce erratic behaviour in DevCpp. For further info
+check the following sites
+
+http://aditsu.freeunixhost.com/dev-cpp-faq.html
+http://sourceforge.net/forum/message.php?msg_id=3252213
+
+As I have mentioned before I will confine this to the SSL Library compilations
+but the process is very similar for compilation of the executable - curl.exe;
+just substitute the src folder makefile in its stead.
+
+First use a text processor Notepad, or your own favourite text processor. To
+engage your favourite text processor, select Makefile.m32 click once with your
+mouse on file icon; icon turns blue, press the shift key and right-click on
+mouse, menu appears select "Open with", select your favourite text processor.
+
+Next read the contents of Makefile.m32. It includes instructions on its use.
+
+Method I - DOS Command Line
+---------------------------
+ 
+Note - The only reason I have included this method is that Method II which is
+the preferred method for compiling does not allow for the setting of option
+switches (e.g. SSL = 1 or SSL =0). At least that's what they tell me at the
+Dev-Cpp forum.
+
+1 - Make a copy of (D:\Dev-Cpp\bin) bin folder and name it "bin Original"
+place it in the Dev-Cpp installed directory (D:\Dev-Cpp\ for this example)
+
+2 - Copy the entire contents of the LIB folder of curl-7.14.0.tar.gz or zip
+version into the bin folder above (D:\Dev-Cpp\bin). The reason being is that
+the make.exe file resides in this folder. Make.exe will use - Makefile.m32,
+Makefile.inc, and the source code included in the lib folder to compile the
+source code. There is a PATH issue with make.exe that remains unresolved at
+least for me. Unless the entire source code to be compiled is placed entirely
+within the directory of make.exe an error message will be generated - "file
+xxxx.yyy not available".
+
+3- Go to Dev-Cpp\bin and double click on make .exe. You will see a DOS window
+quickly pop up and close very quickly. Not to worry! Please do not skip this
+step.
+
+4- Click on the start button\Programs\MS-DOS Prompt.Once the DOS Window is up
+Type the disk drive letter (e.g. E: ) engage the enter button. The path should
+automatically take you to the directory of the make.exe file.
+
+5- To compile the source code simply type at the DOS prompt make -f
+Makefile.m32 as per instructions contained in the Makefile.m32 file (use any
+text processor to read instructions). I don't believe that this makefile
+allows for the option of non SSL. Ignore any warnings.
+
+6- Collect and make copies of libcurl.a, libcurl.dll, libcurldll.a and any *.o
+compilations you might need in another directory outside of the bin directory
+as you will need this files shortly to set up libcurl for use with
+Dev-cpp. For most apps *.o is not required. Later on we will show what to do
+with these files.
+
+7- You are finished but before closing we need to do cleanup - erase the bin
+folder and rename the "bin Original" folder created in step 1 to bin.
+
+Note to compile a curl executable the process is probably similar but instead
+of using the LIB folder contents use the SRC folder contents and Makefiles in
+curl-7.14.0.tar.gz. File directories relative placements must be respected for
+compiling to take place successfully. This may not be possible with the PATH
+problem that make.exe experiences. If anyone has solved this PATH issue and
+please make sure it actually works on Win 9x/2000/XP before letting me
+know. Then please let me or Daniel in on the solution so that it can be
+included with these instructions. Thanks.
+
+or
+
+Method II - Dev-Cpp GUI
+-----------------------
+
+1- Copy the entire contents of the LIB folder of curl-7.14.0.tar.gz or zip
+version into any folder outside of (Dev-Cpp\bin).
+
+2- Drop the File/New/click on Project.
+
+3- New Project Dialogue box appears. Double click on the Static Library.
+
+4- Create Project Dialogue box appears. Select the LIB folder location to
+place and locate your Project File Name. Placing the Project File Name
+elsewhere may cause problems (PATH issue problem again).
+
+5- Drop down the Project/Project Options. Project Options Dialogue box
+appears.
+
+6- Select the Makefile tab in the Project Options Dialogue Box. Check Box -
+Use Custom Makefile. Click on the Folder icon at the extreme right of the
+Check Box. Select Makefile.m32 in the folder wherever you have placed the
+contents of the LIB Folder. Press OK and close the Dialogue Box.
+
+7- Drop the Menu Project/Click on Add to Project. Open File Dialogue Box
+appears.  The Dialogue Box should open in the folder wherever you have placed
+the contents of the LIB Folder. If not go there.
+
+8- Select Crtl-A to select all files in the LIB folder. Click on open to add
+files and close box. Wait till all files are added. This may take 30 seconds
+or longer.
+
+9- Drop the Menu Execute/Click on Compile. 
+
+10- That's it.
+
+
+   The following steps must be completed if Curl is to work properly
+   =================================================================
+
+LIB folder inclusions (*.a placement)
+-------------------------------------
+
+1- Refer to Method I - DOS Command Line point # 6 Take libcurl.a, libcurldll.a
+and install it in the directory C( or whichever drive Dev is installed)
+:\Dev-Cpp\lib.
+
+
+Include Folder
+--------------
+
+1- Create a new folder by the name of curl (do not change the name curl to
+some other name as it will cause major issues) in the directory
+C:\Dev-Cpp\include.
+
+2- Copy the entire contents of the curl folder of curl-7.14.0.tar.gz or zip
+ version into the newly created curl directory - C:\Dev-Cpp\include\curl.
+
+Links To Include And Lib Folder
+-------------------------------
+
+1- Drop the Menu - Tools\Compiler Options\Directories\Libraries. Make sure
+that C( or whichever drive Dev is installed):\DEV-CPP\lib is included.
+
+2- Next select the Menu - Tools\Compiler Options\Directories\C Includes. Make
+sure that C:\DEV-CPP\include and C:\Dev-Cpp\include\curl are included.
+
+3- Next select the Menu - Tools\Compiler Options\Directories\C++
+Includes. Make sure that C:\DEV-CPP\include and C:\Dev-Cpp\include\curl are
+included.
+
+Linker Links
+------------
+
+1- Drop the Menu - Tools\Compiler Options\Directories\Compiler.
+
+2- Make sure that the box "Add these commands to the linker command line" is
+checked.
+
+3- Include in the white space immediately below the box referred in 2 -lcurl
+-lws2_32 -lwinmm.
+
+SSL Files
+---------
+
+1- Get the latest openSSL (as of time of this writing)
+openssl-0.9.7e-win32-bin.zip for the minimalist package of the openssl-0.9.7e
+binaries ported to MS Windows 95/98/NT/XP using the MingW32/GCC-3.1
+development environment. The file may be downloaded at
+http://curl.haxx.se/download/.
+
+2- Open the above zip file. You will find two files - SDL.dll,
+SDL_mixer.dll. Install them in the directory C:\WINDOWS\SYSTEM32 for Win 9x
+users and c:\winnt\system32 for NT-family users.
+
+Multithreading Files
+--------------------
+
+To be completed
+
+#define
+-------
+
+1- Make sure that your program includes the following - #define CURL_STATICLIB
+must be declared FIRST before any other define functions may be
+added. Otherwise you may experience link errors.
+
+2- Don't forget to include   #include "curl/curl.h".
+
+e.g.
+    #define CURL_STATICLIB 
+#include <windows.h>
+    #include "curl/curl.h"
+#include <fstream>
+#include <iostream>
+#include <vector>
+etc...
+
+
+Static or Dynamic Library
+-------------------------
+
+The above steps apply for the use by a static library. Should you choose to
+use a dynamic library you will be required to perform these additional steps.
+
+1- Refer to Method I - DOS Command Line point # 6. Install libcurl.dll in the
+directory C:\WINDOWS\SYSTEM32 for Win 9x users and c:\winnt\system32 for
+NT-family users.
+
+2- Refer to Linker Links point 3 - Replace -lcurl with -lcurldll.
+
+Voila you're done.
+
+The non-SSL static Library build may not be possible to use at least as of the
+time of this writing - v7.14. Check reference emails - Phillipe and I found it
+impossible to fully compile as certain files were missing for linking. No big
+loss as SSL is a major plus.
+
+Hope this Helps
+
+Tom
diff --git a/docs/Makefile.am b/docs/Makefile.am
index 08743aadf..387218ef5 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -14,10 +14,10 @@ SUBDIRS = examples libcurl
 
 CLEANFILES = $(GENHTMLPAGES) $(PDFPAGES)
 
-EXTRA_DIST = MANUAL BUGS CONTRIBUTE FAQ FEATURES INTERNALS SSLCERTS	\
- README.win32 RESOURCES TODO TheArtOfHttpScripting THANKS VERSIONS	\
- KNOWN_BUGS BINDINGS $(man_MANS) $(HTMLPAGES) HISTORY INSTALL		\
- $(PDFPAGES) LICENSE-MIXING README.netware DISTRO-DILEMMA
+EXTRA_DIST = MANUAL BUGS CONTRIBUTE FAQ FEATURES INTERNALS SSLCERTS	 \
+ README.win32 RESOURCES TODO TheArtOfHttpScripting THANKS VERSIONS	 \
+ KNOWN_BUGS BINDINGS $(man_MANS) $(HTMLPAGES) HISTORY INSTALL		 \
+ $(PDFPAGES) LICENSE-MIXING README.netware DISTRO-DILEMMA INSTALL.devcpp
 
 MAN2HTML= roffit < $< >$@