jpeglib.h: Document the need to include stdio.h
libjpeg.txt documents the need to "include system headers that define at least the typedefs FILE and size_t" before including jpeglib.h. However, some software developers unfortunately assume that any downstream build failure is due to an upstream oversight (as if such an oversight would have gone unnoticed for 14 years in a library as ubiquitous as libjpeg-turbo) and "come in hot" with a proposal and arguments that have already been carefully considered and rejected multiple times (as opposed to grepping the documentation or searching existing issues and PRs to find out whether the upstream behavior is intentional.) Multiple issues and PRs (including #17, #18, #116, #737, and #766) have been filed regarding this, so this commit adds a comment to jpeglib.h in the hope of heading off future issues and PRs. I suspect that some people will still choose to waste my time by arguing about it, even though the decision was made by Tom Lane nearly 20 years before libjpeg-turbo even existed, the decision was supportable based on the needs of early 1990s computing systems, and reversing that decision would break backward API compatibility (which is one of the reasons that many downstream projects adopted libjpeg-turbo in the first place.) At least now, if someone posts an issue or PR about this again, I can just link to this commit and close the issue/PR without comment.
This commit is contained in:
12
jpeglib.h
12
jpeglib.h
@@ -7,7 +7,7 @@
|
|||||||
* Lossless JPEG Modifications:
|
* Lossless JPEG Modifications:
|
||||||
* Copyright (C) 1999, Ken Murchison.
|
* Copyright (C) 1999, Ken Murchison.
|
||||||
* libjpeg-turbo Modifications:
|
* libjpeg-turbo Modifications:
|
||||||
* Copyright (C) 2009-2011, 2013-2014, 2016-2017, 2020, 2022-2023,
|
* Copyright (C) 2009-2011, 2013-2014, 2016-2017, 2020, 2022-2024,
|
||||||
D. R. Commander.
|
D. R. Commander.
|
||||||
* Copyright (C) 2015, Google, Inc.
|
* Copyright (C) 2015, Google, Inc.
|
||||||
* For conditions of distribution and use, see the accompanying README.ijg
|
* For conditions of distribution and use, see the accompanying README.ijg
|
||||||
@@ -18,6 +18,16 @@
|
|||||||
* and perhaps jerror.h if they want to know the exact error codes.
|
* and perhaps jerror.h if they want to know the exact error codes.
|
||||||
*/
|
*/
|
||||||
|
|
||||||
|
/* NOTE: This header file does not include stdio.h, despite the fact that it
|
||||||
|
* uses FILE and size_t. That is by design, since the libjpeg API predates the
|
||||||
|
* widespread adoption of ANSI/ISO C. Referring to libjpeg.txt, it is a
|
||||||
|
* documented requirement that calling programs "include system headers that
|
||||||
|
* define at least the typedefs FILE and size_t" before including jpeglib.h.
|
||||||
|
* Technically speaking, changing that requirement by including stdio.h here
|
||||||
|
* would break backward API compatibility. Please do not file bug reports,
|
||||||
|
* feature requests, or pull requests regarding this.
|
||||||
|
*/
|
||||||
|
|
||||||
#ifndef JPEGLIB_H
|
#ifndef JPEGLIB_H
|
||||||
#define JPEGLIB_H
|
#define JPEGLIB_H
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user