Free Pascal 및 Lazarus 지원

HotXLS는 Windows Win32 및 Win64에서 Free Pascal 3.2.2와 Lazarus/LCL을 지원합니다. XLS/XLSX 통합 문서 API, 수식, 서식, 직접 스트리밍, TDataToXLS 및 TGridToXLS 내보내기 구성 요소, 렌더링 도우미가 포함됩니다

네이티브 Linux 및 macOS 통합 문서 코어

범위 지정 디렉터리 API, 명시적 네이티브 저장소 소유권, 타임스탬프, 정식 클래식 식별자 키는 컴파운드 파일 저장소를 참고하세요

옵트인 LX_PORTABLE_CORE 프로필은 Linux와 macOS에서 LCL 없이 TXLSWorkbook과 TXLSXWorkbook을 노출합니다. 네이티브 Linux x64와 macOS ARM64는 Free Pascal 3.3.1로 컴파일되고 실행되었습니다. 소스 버전 가드는 최소 3.2.2를 요구하지만, 그 최소값이 모든 네이티브 컴파일러와 대상 조합이 검증되었다는 주장은 아닙니다

HotXLS 단위 앞에 cthreads와 cwstring을 두고, 단위·포함 경로에 Lib를 추가하고, 빌드 전체에 LX_PORTABLE_CORE를 정의하세요. 네이티브 콘솔 애플리케이션에는 Interfaces나 LCL widgetset이 필요 없습니다

유니코드 파일 시스템 경로를 다룰 때는 애플리케이션 환경에서 설치된 UTF-8 로캘을 선택하세요. 잘못되었거나 UTF-8이 아닌 로캘은 네이티브 RTL 파일 이름 변환을 손상시킬 수 있습니다. 검증 도우미는 로캘을 바꾸거나 코드페이지를 추측하는 대신 그런 환경을 명시적으로 거부합니다

program NativeWorkbookExample;
{$mode delphiunicode}
uses
  cthreads, cwstring, SysUtils, lxHandleX;
var
  Workbook: TXLSXWorkbook;
begin
  Workbook:= TXLSXWorkbook.Create;
  try
    Workbook.Sheets.Add('Data').Cells[1, 1].Value:= 5;
    Workbook.Sheets[1].Cells[1, 2].Formula:= 'A1*2';
    if Workbook.Recalculate> 1 then
      raise Exception.Create('Workbook calculation failed');
    if Workbook.SaveAs('native.xlsx')> 1 then
      raise Exception.Create('Workbook save failed');
  finally
    Workbook.Free;
  end;
end.

열기·저장 메서드는 기존 결과 코드와 진단 계약을 유지합니다. 플랫폼 경계를 직접 넘는 호출은 EXLSPlatformUnsupported를 발생시킬 수 있으므로, 공용 애플리케이션 코드에서 Windows 전용 서비스를 부를 때 이 예외를 처리하세요

재현 가능한 네이티브 검증

기존 Free Pascal 툴체인, Python 3, 네이티브 C 컴파일러를 갖춘 네이티브 게스트에서 검증 도우미를 실행하세요. 게스트 파일 시스템에서 소스 체크아웃 밖의 새 디렉터리나 빈 디렉터리를 출력 디렉터리로 고르세요

python3 Tests/Lazarus/run_native_core.py --fpc /path/to/fpc --output /guest-local/hotxls-validation
python3 Tests/Lazarus/run_native_core.py --fpc /path/to/fpc --config /path/to/fpc.cfg --output /guest-local/hotxls-validation-2

도우미는 소스 입력을 복사해 해시하고, FPC의 대소문자 구분 파일 이름 검색을 위해 비공개 빌드 복사본에서 Pascal 단위 파일 이름을 정규화하고, PCRE2를 로컬에서 빌드하고, 코어·AES·압축·REGEX·공개 통합 문서·통합 목격자를 실행합니다. 체크아웃을 바꾸거나 도구를 설치하거나 컴파일러 설정을 편집하지 않고 소스 매니페스트, 컴파일러 로그, 산출물, 실패 기록을 보존합니다. macOS ARM64 빌드는 명시적으로 macOS 11 이상을 대상으로 합니다

통합 목격자에는 유니코드 경로, Excel이 만든 XLSB 픽스처, 수식 캐시와 재계산, 반복 열기, 희소 ODS 메모와 보호, checked 변환 거부, 호출자 대상을 보존하는 취소, 불변 범위 지정 이름 조회, 실제 워커 실패 봉쇄, 암호화 난수 바이트가 포함됩니다

네이티브 클래식 XLS 계약

클래식 TXLSWorkbook에는 lxHandle를, TXLSXWorkbook에는 lxHandleX를 사용하세요. 클래식 Recalculate는 오류 개수를 반환하므로 0이 성공이고, Calculate 메서드는 수식 결과를 반환합니다. 클래식 셀 Formula 할당에는 선행 =가 필요합니다. 통합 문서 열기·저장 메서드는 기존의 성공 결과 1을 유지합니다

네이티브 클래식 저장소 구현은 실제 컴파운드 파일 계층과 스트림 ID를 사용해 중첩 범위, MiniFAT 데이터, 확장 DIFAT 체인을 보존합니다. 스트림 페이로드는 구체화되고, 라이터는 지원하는 부호 있는 32비트 버퍼/섹터 경계를 넘는 집계 출력을 내보내기 전에 거부합니다. 멀티기가바이트 스트리밍 저장소 구현이 아닙니다

네이티브 컴파운드 저장소는 직접 스트림 작업, 열거, 메타데이터, 복사 작업을 제공합니다. 트랜잭션 롤백, 영역 잠금, 이동, 지원되지 않는 제외 모드는 명시적인 저장소 오류를 반환합니다. Windows COM, 클립보드, GDI 서비스를 에뮬레이트하지 않습니다

클래식 네이티브 파일 저장은 등록된 형제 파일을 원자적으로 교체하기 전에 직렬화합니다. 호출자 스트림 저장은 원래 위치에서 복사하기 전에 컴파운드 파일 전체를 스테이징해 접두부와 커밋 전 취소 실패를 보존합니다. 마지막 진행 알림은 취소 불가입니다. 직접 컴파운드 저장소 도우미 쓰기는 공개 통합 문서 저장 트랜잭션이 아니라 기존 직접 쓰기 계약을 따릅니다

일반 요약(summary) 및 문서 요약(document-summary) 속성은 유니코드 텍스트와 UTC FILETIME 타임스탬프를 갖춘 경계가 있는 표준 OLE 속성 집합을 사용합니다. 클래식 통합 문서 데이터를 암호화해도 이 속성 스트림은 평문으로 남고, RC4 CryptoAPI 헤더가 그 선택을 명시적으로 기록합니다. 정의된 이름은 XLSX 파사드가 쓰는 고정된 정식 식별자 키를 공유하면서 원래 철자와 명시적 워크시트 범위를 유지합니다. 인코딩된 PNG/JPEG 드로잉 데이터는 모델에서 계속 쓸 수 있고, 네이티브 비트맵/메타파일 변환은 별도의 지원 렌더러가 필요하며 그렇지 않으면 EXLSPlatformUnsupported를 발생시킵니다

Tests/Lazarus/HotXLSNativeClassicWorkbookSmoke.lpr를 같은 네이티브 코어 옵션으로 컴파일한 뒤, Tests/Fixtures/classic-native/native-classic.xls, 게스트 로컬의 임시 출력 경로, Tests/Fixtures/classic-native/native-classic-encrypted.xls를 넘기세요. 컨트롤은 Excel이 만든 캐시, 재계산, 정확한 유니코드 이름, 평문·암호화 라운드트립, 독립적으로 디코딩된 속성 타임스탬프, 반복 열기, 16 MB 넘는 SST 데이터, 호출자 출력 보존을 다룹니다

레거시 BIFF 바이트 인코딩

TXLSWorkbook.SetCodePage는 SaveAs(..., xlExcel5)가 쓰는 명시적 바이트 인코딩을 선택하며 기본값은 CP1252입니다. 사용 가능한 0이 아닌 CODEPAGE 레코드가 있는 BIFF2–BIFF5 파일을 가져오면 이후 레거시 저장에도 그 페이지를 선택합니다

레거시 셀 레이블, 수식 텍스트 상수와 배열, 캐시된 수식 문자열, 정의된 이름, 워크시트 이름과 참조, 폰트 이름, 숫자 서식, 스타일 이름, 머리글, 바닥글, 일반 주석 텍스트는 운영체제 로캘이나 UTF-8이 아니라 선언된 페이지를 사용합니다

레코드 길이와 워크시트 스트림 오프셋은 인코딩된 바이트를 셉니다. 기존 255바이트 레거시 레이블과 수식 리터럴 한도는 문자 경계에서만 잘라내므로 CP932 2바이트 문자가 쪼개지지 않습니다. 1바이트 길이를 가진 이름과 메타데이터는 표현 가능한 길이를 넘는 인코딩 텍스트에서 잘못된 길이를 내보내는 대신 거부합니다

선택한 코드페이지로 라운드트립할 수 없는 텍스트는 조용히 대체 문자나 근사 문자가 되기 전에 EConvertError를 발생시킵니다. 문서 텍스트를 표현하는 페이지를 고르거나, 유니코드 문자열이 필요하면 BIFF8로 저장하세요

CONTINUE 레코드에 걸친 수식 캐시 문자열은 디코딩 전에 바이트로 조립되므로, 레코드 경계가 2바이트 문자를 쪼개도 캐시 값은 깨지지 않습니다

선택한 페이지를 바꾸면 형식화된 레거시 수식과 정의된 이름 바이트를 유니코드 모델에서 다시 만듭니다. BIFF8 저장은 계속 유니코드를 쓰고 디스크의 CODEPAGE 값은 1200으로 유지됩니다

가져온 BIFF5 차트 레코드는 형식화된 계열과 붙은 제목 검사를 위해 원래 코드페이지를 유지하며, 통합 문서 코드페이지 편집이나 차트 복사 뒤에도 그렇습니다. 다른 페이지로 저장할 때는 보존된 바이트를 새 선언 아래에서 재해석하는 대신 지원되는 SeriesText, 평문 캐시 레이블, 수식 문자열, 머리글, 바닥글, 현재 통합 문서 외부 시트 이름을 명시적으로 트랜스코딩합니다

이어지는 차트 텍스트, 모델링되지 않은 레거시 외부 시트 인코딩, 불투명한 레거시 바이트 텍스트 레코드는 코드페이지 마이그레이션을 EConvertError로 거부합니다. 표현 불가능한 지원 텍스트도 거부하며, 공개 통합 문서 저장은 커밋 전에 호출자 대상을 보존합니다. 이 텍스트 계약은 완전한 네이티브 차트 모양 변환을 약속하지 않습니다

BIFF5 사용자 지정 스타일 이름은 1바이트 인코딩 길이 바로 뒤에서 시작하고, BIFF5 SeriesText는 유니코드 플래그 없이 식별자와 1바이트 인코딩 길이를 갖습니다. BIFF8 SeriesText는 유니코드 플래그를 더하며, 지원되는 차트 텍스트 변환은 그 레코드와 차트 BOF 버전을 함께 갱신합니다

비어 있지 않은 BIFF5 차트 머리글과 바닥글은 255바이트 최대치의 1바이트 인코딩 길이를 쓰고, 캐시된 LABEL과 STRING 레코드는 2바이트 길이를, BIFF8 머리글과 바닥글은 유니코드 플래그와 함께 2바이트 UTF-16 길이를 씁니다. 마이그레이션은 각 레코드의 실제 레이아웃을 검사하고, 덧붙이기 전에 과대한 레거시 머리글·바닥글은 ERangeError로 거부합니다

HotXLS는 Windows, Linux, macOS에서 레거시 바이트를 선언된 페이지로 해석합니다. 설치된 Excel 16.0 빌드 20430은 수신자 한계를 독립적으로 보여 주었습니다. 네이티브 파일의 CODEPAGE 레코드만 CP1252나 CP932로 바꾼 뒤에도 이 Excel은 자기 로컬 Windows CP936으로 레거시 바이트를 해석했으므로, 올바르게 선언된 바이트가 그 수신 구성에서 일치하는 텍스트를 보장하지는 않습니다

BIFF5를 서로 다른 로캘 구성에 배포할 때는 문서의 실제 인코딩 선언을 보존하고 수신 애플리케이션을 테스트하세요. 유니코드 BIFF8은 이 레거시 바이트 상호 운용 경계를 피합니다

이 바이트 인코딩 수정은 기존 BIFF5 일반 주석 레코드 크기 한도를 유지합니다. 레거시 레코드에 주석 작성자, 리치 텍스트 서식, 도형 지오메트리 필드를 더하지는 않습니다

VBA 모듈 소스 편집은 프로젝트가 선언한 바이트 코드페이지를 사용하고 소스 오프셋 앞의 바이너리 접두부(삽입된 NUL 바이트 포함)를 보존합니다. 이는 저장된 소스 텍스트를 바꿀 뿐 매크로를 실행하지는 않습니다

fHighByte = 0인 BIFF8 압축 유니코드는 각 바이트를 U+0000부터 U+00FF까지의 UTF-16 코드 단위에 직접 매핑합니다. 비표준 CODEPAGE 레코드가 BIFF8 파일에 있더라도 CP1252, UTF-8, 파일의 레거시 코드페이지가 아닙니다

네이티브 텍스트 수식은 서러게이트 쌍 코드 단위를 포함해 UTF-16 길이와 위치를 유지합니다. Unicode LOWER, UPPER, SEARCH, TEXTBEFORE/TEXTAFTER의 대소문자 무시 구분자, 데이터베이스 필드 헤더, 대소문자 무시 조건, 동적 텍스트 키는 호스트 C 로캘의 ASCII 전용 대소문자 함수 대신 네이티브 컴파일러의 유니코드 문자 데이터를 사용하며, 일반 워크시트 정렬은 기존 로캘 비교를 유지합니다

네이티브 LET/LAMBDA 로컬 이름 매칭과 로컬 배열 저장소 분류도 같은 유니코드 인식 대소문자 처리를 사용하므로, 대소문자 짝이 올바른 캡처 바인딩을 해석하고 배열 형태를 유지합니다. 고정된 공개 정의된 이름 ID 계약은 바뀌지 않습니다

클래식 대소문자 무시 FindText와 ReplaceText는 네이티브 FPC에서 리터럴 및 Excel 와일드카드 검색에 유니코드 문자 매칭을 유지합니다. MatchCase는 여전히 대소문자를 구별하고, 리터럴 치환은 replace-all 동작을, 와일드카드 치환은 기존의 최좌측 구간 동작을 유지하며, 수식 셀은 여전히 제외됩니다

Tests/Lazarus/HotXLSNativeLegacyEncodingSmoke.lpr를 네이티브 코어 옵션으로 컴파일하고 임시 출력 디렉터리 뒤에 Tests/Fixtures/legacy-encoding/native-biff5-cp936-chart.xls를 넘기세요. 목격자는 선언된 CP1252·CP932·CP936 바이트를 독립적으로, 모든 워크시트 오프셋을, 코드페이지 변경을, 2바이트 연속 경계를, 압축 BIFF8 가져오기를, 수식 계산을, 네이티브가 만든 차트 텍스트를, 실패한 저장의 대상 보존을 검사합니다

풀 설치 관리자

풀 설치 관리자는 Lazarus를 감지하고 RAD Studio 없이도 설치할 수 있습니다. IDE Integration 페이지에서 Lazarus / Free Pascal을 선택하면 런타임 패키지, 호환 단위, 빌드 스크립트가 설치됩니다. Lazarus만 감지된 IDE일 때는 이 옵션이 기본으로 선택되어 있습니다

Post-install Compilation 페이지에서 Win32 또는 Win64용 Free Pascal 런타임 패키지를 선택합니다. 컴파일러, RTL, LCL, LazUtils 단위가 감지된 대상만 선택할 수 있고, 대상을 사용할 수 없어도 패키지 소스는 설치해 두고 나중에 컴파일할 수 있습니다

이 패키지는 런타임 전용이며 Lazarus에서 프로젝트 종속성으로 추가됩니다. 설치 관리자가 VCL 데모를 Free Pascal로 컴파일하지는 않습니다

빌드 및 테스트

Lazarus에서 Lib/FPC/HotXLSLaz.lpk를 열어 런타임 패키지를 컴파일하거나, HotXLS 디렉터리에서 다음 명령을 실행합니다

build-FPC-Lib.cmd Win64
Tests\Lazarus\Run-HotXLSLazarusSmoke.cmd Win64
build-FPC-Lib.cmd Win32
Tests\Lazarus\Run-HotXLSLazarusSmoke.cmd Win32

설치를 선택하려면 LAZARUS_DIR을 설정합니다. 필요할 때 FPC_EXE와 LAZBUILD_EXE로 명시적인 컴파일러와 패키지 빌더를 지정할 수 있습니다

선택한 설치에는 대상 아키텍처용 FPC와 컴파일된 LCL/LazUtils 단위가 포함되어 있어야 합니다. 출력과 패키지 빌더 구성은 아키텍처별 별도 디렉터리에 유지됩니다

응용 프로그램 설정

단위 검색 경로에 Lib와 Lib/FPC를, 포함 검색 경로에 Lib를 추가하거나, 런타임 패키지를 Lazarus 프로젝트 종속성으로 추가합니다

콘솔 응용 프로그램을 포함해 응용 프로그램의 uses 목록에서 HotXLS 단위 앞에 Interfaces를 둡니다. 이는 RTL/LCL 경계에서 LCL widgetset과 UTF-8 변환을 초기화합니다

program WorkbookExample;
{$mode delphiunicode}
uses
  Interfaces, SysUtils, lxHandleX;
var
  Workbook: TXLSXWorkbook;
begin
  Workbook:= TXLSXWorkbook.Create;
  try
    Workbook.AddSheet('Data');
    Workbook.Sheets[1].Cells[1, 1].Value:= 'Hello';
    if Workbook.SaveAs('example.xlsx')<> 1 then
      raise Exception.Create('Workbook save failed');
  finally
    Workbook.Free;
  end;
end.

HotXLS 소스 단위는 내부적으로 Delphi Unicode 의미 체계를 선택하므로 문자열, 문자, 수식 텍스트가 UTF-16 동작을 유지합니다. 애플리케이션 코드는 선호하는 Pascal 모드를 사용할 수 있습니다

호환성 세부 사항

• 런타임 패키지는 Windows와 LCL이 필요합니다. TDataToXLS는 LCL 데이터셋을, TGridToXLS는 명시적 열 지정 여부와 관계없이 TDBGrid를 내보냅니다. Linux, macOS, VCL 데모 폼, VCL workbook viewer, DevExpress 그리드 어댑터는 이 패키지 범위 밖입니다
• ZIP과 압축 스트림은 번들된 Pascal 백엔드를 사용하므로 별도의 zlib DLL이 필요 없습니다
• AES는 두 아키텍처 모두 Pascal 백엔드를 사용하며 암호로 보호되는 XLSX 파일도 포함합니다
• PNG는 알파를 보존하고, EMF는 Windows 메타파일 기록·재생을 사용하며, 다중 페이지 TIFF는 Windows GDI+ 런타임을 사용합니다
• 직접 텍스트 읽기는 UTF-8과 BOM이 있는 UTF-16/UTF-32를 받고 스트리밍 입력을 처리하며 호출자의 스트림 소유권을 유지합니다
• 개별 필드를 변경하기 전에 TXlsCsvImportOptions를 TXlsCsvImportOptions.Default로 초기화합니다
• FPC 보고서 식과 임포트 패턴은 Delphi의 PCRE 백엔드 대신 Unicode URegExpr 구문을 사용합니다. 빈 입력에 대한 답은 TRegEx와 같습니다. ^$나 .*처럼 빈 문자열을 받아들이는 패턴은 매치되고 [0-9]+는 매치되지 않으며, 빈 문자열에 대한 치환은 패턴이 빈 문자열을 받아들일 때만 치환 텍스트를 산출합니다. 지원되지 않는 패턴과 빈 패턴은 ERegularExpressionError를 발생시키며, 보고서 식은 이를 REPORT_EXPRESSION_INVALID_REGEX로 노출합니다