classification
Title: Wrong linking terminology in windows FAQ
Type: Stage:
Components: Documentation Versions: Python 3.1, Python 3.2, Python 2.7, Python 2.6
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, georg.brandl, john.miller, loewis, skrah, terry.reedy
Priority: normal Keywords:

Created on 2010-06-26 10:05 by john.miller, last changed 2010-10-17 10:15 by georg.brandl. This issue is now closed.

Messages (4)
msg108700 - (view) Author: John Miller (john.miller) Date: 2010-06-26 10:05
The 'How can I embed Python' section in the 'Python on Windows FAQ' (http://docs.python.org/faq/windows.html) uses wrong terms:
What the FAQ calls static linking and dynamic linking are actally two forms of dynamic linking - load-time dynamic linking and run-time dynamic linking, respectively.
Static linking means something else entirely - linking with a library that itself contains the implementation, i.e. there will be no usage of the DLL at all. Since the FAQ states that pythonNN.lib is just an import lib, static linking isn't really an option with this library.

Also the FAQ states that 'The drawback to dynamic linking is that your app won’t run if pythonNN.dll does not exist on your system'. This is misleading for two reasons:
- If the application uses the DLL, it won't run as expected if the DLL doesn't exist, regardless of how it loads the DLL. 
- Of the two linking options, load-time dynamic linking (what the FAQ refers to as static linking) is actually the one that handles the missing DLL more badly: The app will crash upon loading. If run-time dynamic linking is used, loading of the DLL happens in the application code, and it can handle it however it chooses to - it can inform the user, disable the feature that needs the DLL, etc.
msg109199 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-07-04 00:25
3.1 docs say same. For *nix, I would agree with your view of 'static', but perhaps MS uses a different terminology. Martin?

Or maybe the doc writer is using a local def of static simply as a terse, if potentially confusing, alternative to 'load-time linking'. But that could just be .lib linking versus .dll linking, which is crystal clear. Can you write an alternative paragraph or two that you think is better?
msg109210 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2010-07-04 08:05
I agree with John: this paragraph is technically incorrect. See

http://msdn.microsoft.com/en-us/library/ms681914%28v=VS.85%29.aspx

for an "official" definition of the relevant terms.

I vaguely recall objecting to that text when it got added, but in the discussion, it would have meant that I would have to rewrite the text myself, which I didn't want to (maybe I'm confusing this with something else, though).

In any case, it would be possible to actually use static linking as well for Python. There are currently no VS projects defined to create a static library, and such a thing couldn't dynamically load modules (which might not be necessary for embedding).

I agree with Terry that it would be best if John would produce some text he's happy with.
msg118924 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-10-17 10:15
Okay, I removed mention of static linking and used John's terms "load-time" and "run-time" linking in r85618.  I also removed the note that pythonXY.dll is only needed in one case, since it's not true.
History
Date User Action Args
2010-10-17 10:15:53georg.brandlsetstatus: open -> closed

nosy: + georg.brandl
messages: + msg118924

resolution: fixed
2010-07-04 08:05:59loewissetmessages: + msg109210
2010-07-04 00:25:51terry.reedysetnosy: + loewis, terry.reedy

messages: + msg109199
versions: + Python 3.1, Python 2.7, Python 3.2
2010-06-26 10:11:22skrahsetnosy: + skrah
2010-06-26 10:05:37john.millercreate