文件列表:

doc/
extra-gir/
fixes-gir/
gimetadata
gir2typelib/
giversion/
mlton-fixes/
release/
src/
version/
COPYING
LICENCE
LICENCE.CODEGEN
Makefile
codegen
mlton-codegen

__ o o __ \_\|__|/_/ (o o)/ Giraffe Code Generator |_ /\ '-'\|\ The code generator for Giraffe Library. \_\ \|\ \_\ You do not need this repository to use Giraffe Library! / |\ The latest release packages and documentation have been /_/\_\ generated for you and are available from /|/ \|\ /_/ \_\ https://giraffelibrary.org/ /|/ \|\ /_/ \_\ Overview The Giraffe Code Generator generates an SML interface to libraries using the GObject Introspection metadata (GIR or TYPELIB files) provided by the libraries. The Giraffe Library source release files are generated using the GIR files only. Originally, the TYPELIB files were used and support is retained for generating code from them but only for comparison, to validate the code generated from GIR files. In addition to the code generator, this repository provides static (i.e. not generated) source release files. The final source release contains both static and generated files. After the code generation steps below are performed, the final source release is in the directory 'release', which can be used as a Giraffe Library release. However, users do not need to generate the release, which may require additional tools, as the latest is available from the website (https://giraffelibrary.org/). This document contains the following sections: 1 Directory contents 2 Working directory initialization 3 Code generation 4 Manual code 5 MLton-specific code generation 1 Directory contents The repository contains the following: README - this file LICENCE - overview of the licences LICENCE.CODEGEN - the licence that covers the code generator source code COPYING - a copy of the GNU GPL version 3 release/ - source release files excluding generated code Makefile - Make file for building source release TAR file codegen - script to perform code generation steps mlton-codegen - script to perform MLton-specific code generation steps src/ - code generator source code version/ - package version of GI metadata files for code generation giversion/ - GI version of GI metadata files for code generation fixes-gir/ - fixes to generated code extra-gir/ - extra code that is not generated mlton-fixes/ - fixes to generated MLton-specific C code gir2typelib/ - script to compare code generated from GIR and TYPELIB data The following are submodules which must be initialized in the working directory, as described in section 2 below, before code generation can be performed: src/ fxp/ - FXP Functional XML parser gimetadata/ - GI (GObject Introspection) metadata files doc/ examples/ - Giraffe Library Examples The following are created in the working directory during code generation: auto-gir/ - code that is generated from GIR files auto-typelib/ - code that is generated from TYPELIB files fixed-gir/ - final version of code for source release mlton-auto/ - MLton-specific C code that is generated from GIR files mlton-fixed/ - final version of MLton-specific C code for source release The following contain the release files after code generation: release/ - Giraffe Library source release files The following are created in the working directory as a result of building the release packages: giraffe-${VERSION}.tar.gz - Giraffe Library source release package 2 Working directory initialization The repository contains submodules that need to be initialized in a working directory. This is done in one of two ways: A. After cloning the repository, e.g. git clone https://github.com/giraffelibrary/giraffe.git initialize and update the submodules with the following commands: git submodule init git submodule update B. When cloning, run git clone with the option --recurse-submodules, e.g. git clone --recurse-submodules \ https://github.com/giraffelibrary/giraffe.git 2.1 GI metadata The GI metadata repository, included as a submodule, indexes GIR and TYPELIB files by package version, GI version and platform. For a particular -, code generation derives - the package version from the first line of the file version/-/version - the GI version from the first line file giversion/-/giversion The platform is always 'x86_64' but note that the generated SML code should not depend on any platform-specific values in GIR files - this would be considered a bug - so it should be possible to use any platform whose metadata is available. 3 Code generation Code generation requires Poly/ML >= 5.6 and common GNU utilities. 3.1 Overview Code is produced in stages: 1. Generate code from GIR files 2. Add non-generated files and, where required, fix generated code 3. Copy final code to the main source tree to be included in the release The output of stage 1 can be checked against code generated from TYPELIB files to add confidence that the GIR files have been interpreted correctly, for example, that correct default values have been assumed. The code is checked in stages: 4. Generate code from TYPELIB files 5. Convert code generated from GIR files to use platform-specific types 6. Compare code from stages 4 and 5 The following diagram shows the data dependencies of these stages: Code from GIR files : Optional check against code from TYPELIB files : .-----------. : .--------------. | GIR files | : | TYPELIB file | `-----------' : `--------------' | 1 : | 4 v : v .----------. : 5 .-------------------. .--------------. | SML code |------:----->| Platform-specific | | SML code | | from GIR | : | SML code from GIR | | from TYPELIB | `----------' : `-------------------' `--------------' | 2 : | | v : `----------. .----------' .----------------. : | 6 | fixed SML code | : v `----------------' : .-------------. | 3 : | GIR/TYPELIB | v : | differences | .------------. : `-------------' | SML source | : | release | : `------------' : 3.2 Commands The codegen script is used to invoke code generation. At present, it performs stages 1, 2, 3 and 4 described above. To see a list of commands, enter ./codegen help Commands that produce code write to a temporary directory under "/tmp". A corresponding "update-..." command copies the code from the temporary directory to the working directory. The update commands do not overwrite any existing code in the working directory and, if existing code is different, it will invoke a merge tool, if defined by the environment variable MERGE, to allow differences to be reviewed. This approach is taken to compare easily differences introduced in the generated code against the original code in the working directory. 3.3 Using GIR files Giraffe Library is generated from GIR files to produce library code that is portable across all platforms. Although GIR files include some platform- specific data, such data is not (or should not be) used. Stage 1 In a working directory, library code is generated in the directory "auto-gir" using the following commands: ./codegen gir ./codegen update-gir Stage 2 Fixed library code is generated in the directory "fixed-gir" by applying fixes to the code in "auto-gir" using the commands ./codegen fixed ./codegen update-fixed Stage 3 The code in "fixed-gir" is copied into the source release directory using the command ./codegen update-source Once no longer required, the code in "fixed-gir" is removed from the source release directory using the command ./codegen remove-source 3.4 Check using TYPELIB files Although it is possible to generate code from TYPELIB files, they are designed for dynamic (run-time) introspection and, for efficiency, are platform-specific. Consequently, TYPELIB files do not have sufficient information to generate portable code because - types are resolved for the platform, for example, glong is - gint32 in the TYPELIB for a 32 bit platform and is - gint64 in the TYPELIB for a 64 bit platform; - the version at which entities are introduced is not stored so, for example, references in C code to struct types cannot be protected for use on platforms with older libraries. Also, alias types are resolved to the underlying type, which reduces traceability to the API documentation. At present, code is generated from TYPELIB files only for the purpose of comparison with code generated from GIR files, to add confidence that the SML GIRepository interface to GIR files is giving correct information. It is planned that code generated from TYPELIB should be usable on the platform that is was generated on, using dynamic linking. Stage 4 The SML bindings to the GIRepository C library require SML bindings for the GLib and GObject namespaces. Therefore, before stage 4 is performed, stages 1 to 3 must be performed and the commands cd release/ ./configure --without-mlton ... make cd .. run in order to build Giraffe C interface libraries for Poly/ML in the source release directory. 'configure' may require extra options, marked '...' if it does not find the required version of Poly/ML. Then library code is generated in the directory "auto-typelib" by the following commands: ./codegen typelib ./codegen update-typelib Stage 5 There is no codegen command to perform stage 5. The script "gir2typelib/convert" should be run from a directory that is a copy of "auto-gir", the code generated from GIR files, that is to be converted. Stage 6 There is no codegen command to perform stage 6. This should be performed manually using the Diff program (or equivalent) to compare "auto-typelib" from stage 4 with the converted code from stage 5. 4 Manual code In the working directory, the following directories contain hand-written code or generated code that has been fixed by hand: fixes-gir/ - code that is fixed to work around Giraffe limitations extra-gir/ - code that is not generated Fixes to generated code are a maintenance burden because any changes in the generated code must be merged manually. Therefore fixes to the generated code should be avoided if possible. In particular, the GIRepository overrides in "src/config.sml" should be updated to override incorrect GIR data if possible. At present, not all data can be overridden so "src/GIRepository.sml" may need to be modified to introduce a new override. "fixes-gir" is used for various reasons. At present, the main reasons are to: - provide modules for a root class of a hierarchy (generated as empty files); - provide modules for callback types (not generated); - introduce abstractions in fundamental GObject modules such as GObject.Type and GObject.Closure; - provide modules for GDK event record types that capture event hierarchy indicated by the GdkEvent union type; "extra-gir" provides source code that is not generated. At present, this includes: - special GObject modules: Signal, Property and ClosureMarshal; - a module to classify, i.e. downcast, a GdkEvent record: ClassifyEvent; - other modules that introduce abstractions. 5 MLton-specific code generation The generated code provides C functions that wrap library functions in order to use a different representation for C array parameters that allows MLton to pass an optional SML vector as an optionally-null C pointer. Note, therefore, that C wrapper functions are generated only for functions with arguments that are vector-like. MLton-specific code generation requires Poly/ML 5.6 and common GNU utilities. 5.1 Overview MLton-specific code is produced in stages: 1. Generate code from GIR files 2. Fix generated code 3. Copy final code to the main source tree to be included in the release The following diagram shows the data dependencies of these stages: Code from GIR files .-----------. | GIR files | `-----------' | 1 v .----------. | C code | | from GIR | `----------' | 2 v .----------------. | fixed C code | `----------------' | 3 v .------------. | C source | | release | `------------' 5.2 Commands The mlton-codegen script is used to invoke code generation stages 1, 2 and 3 described above. To see a list of commands, enter ./mlton-codegen help Commands that produce code write to a temporary directory under "/tmp". A corresponding "update-..." command copies the code from the temporary directory to the working directory. The update commands do not overwrite any existing code in the working directory and, if existing code is different, it will invoke a merge tool, if defined by the environment variable MERGE, to allow differences to be reviewed. This approach is taken to compare easily differences introduced in the generated code against the original code in the working directory. The C function wrapper code is produced only from GIR files because the required information is not stored in TYPELIB files. Stage 1 In a working directory, library code is generated in the directory "mlton-auto" by the following commands: ./mlton-codegen auto ./mlton-codegen update-auto Stage 2 Fixed library code is generated in the directory "mlton-fixed" by applying fixes to the code in "mlton-auto" using the commands ./mlton-codegen fixed ./mlton-codegen update-fixed Stage 3 The code in "mlton-fixed" is copied into the source release directory by the command ./mlton-codegen update-source Once no longer required, the code in "mlton-fixed" is removed from the source release directory by the command ./mlton-codegen remove-source

近期下载者：

相关文件：

评论：[我要评论] [举报此文件]

收藏者：