STR #2642: Need examples and docs for how to build apps against DLL version of FLTK

STR #2642

Application:	FLTK Library
Status:	1 - Closed w/Resolution
Priority:	1 - Request for Enhancement, e.g. asking for a feature
Scope:	2 - Specific to an operating system
Subsystem:	Core Library
Summary:	Need examples and docs for how to build apps against DLL version of FLTK
Version:	1.4-feature
Created By:	greg.ercolano
Assigned To:	AlbrechtS
Fix Version:	1.4.0
Fix Commit:	727bd94560ca9056cdbe40fe2e7923ed008b6eac
Update Notification:	Receive EMails Don't Receive EMails

Trouble Report Files:

#1	AlbrechtS 08:07 Aug 08, 2016

cmake_test_shared.diff
1k

Trouble Report Comments:

#1	greg.ercolano 17:10 May 23, 2011

The recent thread on fltk.general seems to make it clear it's currently non-trivial or unknown on how one goes about linking a /subsystem:windows application against FLTK using the Microsoft compiler (eg. VS2010). I believe the test programs all demonstrate static linkage (they link against fltk.lib). Docs should cover how to link against fltkdll with /subsystem:windows, and details in the OS section should describe the deal with WinMain() and how it gets defined. Comments above the FLTK definitions for WinMain() in fl_call_main.cxx should probably be more descriptive as well about how the macros therein are intended to operate when linking against DLLs.

#2	greg.ercolano 19:04 May 23, 2011

Oh, and that thread being Subject: "Link Errors / Visual C++ 2010 Express" regarding errors linking a DLL fltk app. I've been trying quite a bit from the cli, and have not found the right combo to get it to work. We should at least have a 'hello dll world' test program that compiles against DLL versions of the lib to make sure it can be done and can be used for reference.

#3	AlbrechtS 01:16 May 24, 2011

Just some thoughts: We can easily change one or more test programs to link with the dll, and we should then document these as examples. I tested this with test/device, and it worked. The test programs /in our FLTK project/ I tested with dll linkage worked w/o explicitly specifying WinMain(), presumably because they /also/ link with the object library fltk.lib, and in this library for static linking we have our WinMain() stub that would normally be used for static linking. I don't yet know why this happens, but there seems to be an implicit dependency ("added by the system") that can't be removed. MS VC++ magic ? In user projects, created from an empty project, we would have to link with fltkdll.lib (only), but then we'd need an explicit WinMain() function provided by the user. One solution would be to link additionally with fltk.lib, so that the same applies as with our FLTK project test programs: they pull WinMain() from the static lib. I don't know whether this is good style, however, since it could come to ambiguities... Another solution could be another header file that the user would have to include to get rid of the need to write a WinMain() function. I just posted it in the above mentioned thread, but here it is again for completeness (code taken and from src/fl_call_main.c and stripped down to a minimum): FL/winmain.h: #ifdef FL_DLL #include <Windows.h> // int main (int, char **); // should probably not be here ? int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine, int nCmdShow) { return main(__argc,__argv); } #endif // FL_DLL So, yes, I agree with Greg. We need to decide what we should suggest and then we should document this. There was also a proposal to let the user change the program entry point to main(), but maybe this doesn't work as expected. A user (Asif) reported that the program didn't exit cleanly when he did that. This needs to be checked. And, last but not least, we could simply document that we provide the WinMain() function only for static linking, and that the user must call his program entry point WinMain(), just as MS wants him to do ;-)

#4	matt 05:09 May 24, 2011

Fluid used to be dynamically linked for a good reason. I t was supposed to accept plugins for additional widgets. This was problematic because Fluid is required to compile the source, so if Fluid can not find the dll for some reason, the entire build will fail. This happened specifiacally when users moved Fluid somewhere els, but did not move the dll. I think that's the reason why Fluid is now statically linked (and can not accept plugins that need a UI). But we could change another test to use the DLL.

#5	matt 06:48 May 26, 2011

Bumped to 1.4

#6	AlbrechtS 08:07 Aug 08, 2016

Much time has passed since the creation of this STR and the discussions. In an attempt to test a shared library build with Visual Studio 2015 I modified our test/CMakeLists.txt file to include two executables with shared linking: test/hello and test/prixmap_browser. I'm attaching a patch (cmake_test_shared.diff) to show how I did it. I could link and execute these executables if and only if the necessary dll's were copied to the test build directory (currently bin/examples/Debug or similar). Note: this is not a complete answer to the question, and it is not a solution to the "missing documentation" issue, but it should help to show how it can be done. My solution compiles src/fl_call_main.c as an additional file (see discussion above).

#7	AlbrechtS 17:51 Jan 01, 2018

When I took a look at this STR I got the impression that our fl_call_main.c (WinMain) function does not support Unicode (UTF-8) argument strings - although there are some conversions included. It seems as if (undocumented?) arguments __wargv[] and/or __argv[] are used and converted. I didn't search for official docs about __wargv[] and/or __argv[] though. I'm not sure, and I didn't test anything, but anyway, so my concerns don't get lost... According to [1] "WinMain cannot be used by Unicode programs. The GetCommandLineW function can be used to obtain the command line as a Unicode string." Maybe GetCommandLineW() is only supported since WinXP though, so that we'd lose the ability to run on Win2000 and older? Again, not sure. The docs of GetCommandLineW() [2] say that CommandLineToArgvW() [3] should be used to retrieve Unicode (i.e. UTF-16) argument strings. We'd have to convert these arguments to UTF-8 and free the memory used by the Unicode argument array and strings with LocalFree() according to [3]. I hope the following links are usable and don't wrap. [1] <https://msdn.microsoft.com/en-us/library/windows/desktop/ms633559(v=vs.85).aspx > [2] <https://msdn.microsoft.com/en-us/library/windows/desktop/ms683156(v=vs.85).aspx > [3] <https://msdn.microsoft.com/en-us/library/windows/desktop/bb776391(v=vs.85).aspx >

#8	AlbrechtS 17:56 Jan 01, 2018

Maybe the following links work better: [1] https://msdn.microsoft.com/en-us/library/windows/desktop/ms633559%28v=vs.85%29.aspx [2] https://msdn.microsoft.com/en-us/library/windows/desktop/ms683156%28v=vs.85%29.aspx [3] https://msdn.microsoft.com/en-us/library/windows/desktop/bb776391%28v=vs.85%29.aspx

#9	AlbrechtS 10:50 Nov 26, 2023

I will take care of this STR, please see GitHub Issue #655 and particularly this comment: https://github.com/fltk/fltk/issues/655#issuecomment-1826865870 Status report: I'm working on a clean way to (a) enable the user program to use WinMain() when necessary (b) convert commandline arguments to UTF-8 (already partially implemented). Further activities will include documentation of the usage of FLTK libs and how to use WinMain(). This will be documented on GitHub, see https://github.com/fltk/fltk/issues/655 . I'm leaving this STR open (status "Active") for now.

#10	AlbrechtS 08:28 Nov 29, 2023

Fixed in Git repository. Progress report: Windows commandline conversion (to UTF-8) has been resolved by commit 727bd94560ca9056cdbe40fe2e7923ed008b6eac. Documentation on how to use the FLTK libs, particularly WinMain() and the DLL's on Windows is still to be done. This will be handled in GitHub Issue #655 (see link above). Closing this STR now.