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:
DRC
2024-05-20 12:13:51 -04:00
parent bc491b16e2
commit 9ddcae4a8f

View File

@@ -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