Praats/external/flac/READ_ME.TXT
Paul Boersma, 20 August 2021
24 February 2024: "Obsolete repairs"

This file describes the adaptations to the FLAC 1.3.3 sources
that are needed to make them compatible with Praat.

The FLAC sources are distributed over multiple folders, which are in different deep
branches of the FLAC root folder, as listed below. We flatten this hierarchy as shown.

flac-1.3.3
	config.cmake.h.in -> flac_config.h
	include
		FLAC
			all.h -> flac_FLAC_all.h
			assert.h -> flac_FLAC_assert.h
			callback.h -> flac_FLAC_callback.h
			export.h -> flac_FLAC_export.h
			format.h -> flac_FLAC_format.h
			metadata.h -> flac_FLAC_metadata.h
			ordinals.h -> flac_FLAC_ordinals.h
			stream_decoder.h -> flac_FLAC_stream_decoder.h
			stream_encoder.h -> flac_FLAC_stream_encoder.h
		share
			alloc.h -> flac_share_alloc.h
			compat.h -> flac_share_compat.h
			endswap.h -> flac_share_endswap.h
			macros.h -> flac_share_macros.h
			private.h -> flac_share_private.h
			safe_str.h -> flac_share_safe_str.h
			win_utf8_io.h -> flac_share_win_utf8_io.h
	src
		libFLAC
			bitmath.c -> flac_bitmath.c
			bitreader.c -> flac_bitreader.c
			bitwriter.c -> flac_bitwriter.c
			cpu.c -> flac_cpu.c
			crc.c -> flac_crc.c
			fixed.c -> flac_fixed.c
			float.c -> flac_float.c
			format.c -> flac_format.c
			include
				private
					all.h -> flac_private_all.h
					bitmath.h -> flac_private_bitmath.h
					bitreader.h -> flac_private_bitreader.h
					bitwriter.h -> flac_private_bitwriter.h
					cpu.h -> flac_private_cpu.h
					crc.h -> flac_private_crc.h
					fixed.h -> flac_private_fixed.h
					float.h -> flac_private_float.h
					format.h -> flac_private_format.h
					lpc.h -> flac_private_lpc.h
					macros.h -> flac_private_macros.h
					md5.h -> flac_private_md5.h
					memory.h -> flac_private_memory.h
					metadata.h -> flac_private_metadata.h
					ogg_decoder_aspect.h -> flac_private_ogg_decoder_aspect.h
					ogg_encoder_aspect.h -> flac_private_ogg_encoder_aspect.h
					ogg_helper.h -> flac_private_ogg_helper.h
					ogg_mapping.h -> flac_private_ogg_mapping.h
					stream_encoder_framing.h -> flac_private_stream_encoder_framing.h
					stream_encoder.h -> UNUSED
					window.h -> flac_private_window.h
				protected
					all.h -> flac_protected_all.h
					stream_decoder.h -> flac_protected_stream_decoder.h
					stream_encoder.h -> flac_protected_stream_encoder.h
			lpc.c -> flac_lpc.c
			md5.c -> flac_md5.c
			memory.c -> flac_memory.c
			metadata_iterators.c -> flac_metadata_iterators.c
			metadata_object.c -> flac_metadata_object.c
			ogg_decoder_aspect.c -> flac_ogg_decoder_aspect.c
			ogg_encoder_aspect.c -> flac_ogg_encoder_aspect.c
			ogg_helper.c -> flac_ogg_helper.c
			ogg_mapping.c -> flac_ogg_mapping.c
			stream_decoder.c -> flac_stream_decoder.c
			stream_encoder.c -> flac_stream_encoder.c
			stream_encoder_framing.c -> flac_stream_encoder_framing.c
			window.c -> flac_window.c
			windows_unicode_filenames.c -> flac_windows_unicode_filenames.c

All these files are put into the single external/flac source folder.
The #include statements are flattened, e.g.
#include private/float.h becomes #include flac_private_float.h.

Any Praat-specific declarations should go in flac_config.h,
so we have to #include flac_config.h in most *.c files.
Including the config file is done in FLAC inside #if HAVE_CONFIG_H,
just as in many other libraries. This is appropriate for libraries that are compiled
separately, but not for libraries that are included in a larger project as source code.
So we remove all instances of #if HAVE_CONFIG_H. Specifically, we replace

#if HAVE_CONFIG_H
#  include <config.h>
#endif

with

//ppgb #if HAVE_CONFIG_H
#include "flac_config.h"
//ppgb #endif

in all *.c files.

We have #ifdef NDEBUG in flac_FLAC_assert.h. That is fine, because Praat wants to keep
assertions in its code.

flac_FLAC_stream_decoder.h:

typedef struct {
	struct FLAC__StreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
	struct FLAC__StreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
} FLAC__StreamDecoder;

into

typedef struct FLAC__StreamDecoder {   //ppgb 20071120
	struct FLAC__StreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
	struct FLAC__StreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
} FLAC__StreamDecoder;

flac_FLAC_stream_encoder.h:

typedef struct {
	struct FLAC__StreamEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
	struct FLAC__StreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
} FLAC__StreamEncoder;

into

typedef struct FLAC__StreamEncoder {   //ppgb 20071120
	struct FLAC__StreamEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
	struct FLAC__StreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
} FLAC__StreamEncoder;

Before #including any FLAC header files, do

#define FLAC__NO_DLL

Obsolete repairs
================

At the end of flac_FLAC_format.h, we used to include the following,
so that file names with special characters were handled correctly on Windows:

// pb 20080502
#if defined (_WIN32) && ! defined (__CYGWIN__)
	#ifndef __cplusplus
		uint32_t * Melder_peek8to32 (const char *string);
		const uint16_t * Melder_peek32to16 (const uint32_t *string);
	#endif
	#define fopen(filename,mode)  _wfopen (Melder_peek32to16 (Melder_peek8to32 (filename)), L"" mode)
#endif

However, from FLAC 1.3.3 on, we just call flac_set_utf8_filenames() in Melder_audiofiles_init().
