{"id":13690505,"url":"https://github.com/galkahana/PDF-Writer","last_synced_at":"2025-05-02T11:31:20.222Z","repository":{"id":37431890,"uuid":"692508","full_name":"galkahana/PDF-Writer","owner":"galkahana","description":"High performance library for creating, modiyfing and parsing PDF files in C++ ","archived":false,"fork":false,"pushed_at":"2025-03-27T19:25:50.000Z","size":131731,"stargazers_count":940,"open_issues_count":50,"forks_count":224,"subscribers_count":57,"default_branch":"master","last_synced_at":"2025-04-25T00:18:18.310Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://www.pdfhummus.com","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/galkahana.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2010-05-29T11:55:59.000Z","updated_at":"2025-04-24T15:13:27.000Z","dependencies_parsed_at":"2024-05-02T00:53:21.411Z","dependency_job_id":"6d68a9b2-cc6d-467b-baba-5844f1f68d56","html_url":"https://github.com/galkahana/PDF-Writer","commit_stats":{"total_commits":486,"total_committers":29,"mean_commits":16.75862068965517,"dds":0.154320987654321,"last_synced_commit":"bc385d6c1cb2cc66eeb664c7e7fdfc5a4a711943"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/galkahana%2FPDF-Writer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/galkahana%2FPDF-Writer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/galkahana%2FPDF-Writer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/galkahana%2FPDF-Writer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/galkahana","download_url":"https://codeload.github.com/galkahana/PDF-Writer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252030171,"owners_count":21683301,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T17:00:20.175Z","updated_at":"2025-05-02T11:31:18.143Z","avatar_url":"https://github.com/galkahana.png","language":"C","readme":"Welcome to PDF-Writer, Also known as [PDFHummus](http://www.pdfhummus.com).   \nPDFHummus is a Fast and Free C++ Library for Creating, Parsing an Manipulating PDF Files and Streams. \n\nDocumentation is available [here](https://github.com/galkahana/PDF-Writer/wiki).\nProject site is [here](http://www.pdfhummus.com). \n\nThere is also a NodeJS module named [MuhammaraJS](https://github.com/julianhille/MuhammaraJS) wrapping PDFHummus PDF library and making it available for that language. It is the current and still supported version of a now deprecated [HummusJS](https://github.com/galkahana/HummusJS) project of mine, which [julianhille](https://github.com/julianhille) maintains.\n\n# First time around\n\nThis is a C++ Project using CMake as project builder.\nTo build/develop You will need:\n\n1. a compiler. for win you can use vs studio. choose community version - https://visualstudio.microsoft.com/\n2. cmake - download from here - https://cmake.org/\n\nGiven that this is a Library and _not_ an executable, you can ignore this cmake setup and just use the code as is by copying the folders into your own project. There are, however, better ways to include the code in your own project. The project cmake setup defines PDFHummus as a package and allows you to import the project directly from this repo (remotely) or by pre-installing the package. The instructions below contains information about building the project locally, testing and installing it, as well as explaining how to use CMake `FetchContent` functionality in order to import the project automatically from this repo\n\nFor documentation about how to use the library API you should head for the Wiki pages [here](https://github.com/galkahana/PDF-Writer/wiki).\n\n# Short tour of the project\n\nThere are 8 folders to this project:\n- **FreeType, LibAesgm, LibJpeg, LibPng, LibTiff, Zlib**: 6 libraries that are dependencies to PDFWriter. They are bundled here for convenience. You don't have to use them to compile PDFWriter, but rather use what versions you have installed on your setup.\n- **PDFWriter**: main folder, includes the library implementation\n- **PDFWriterTesting**: test folder, includes test source code that's used with cmake testing application - ctest.\n\n# Building, Installing and testing the project with CMake\n\nOnce you installed pre-reqs, you can now build the project.\n\n## Create the project files\n\nTo build you project start by creating a project file in a \"build\" folder off of the cmake configuration, like this:\n\n```bash\nmkdir build\ncd build\ncmake ..\n```\n\n### options for generating Cmake project files\n\nThe project defines some optional flags to allow you to control some aspects of building PDFHummus.\n\n- `PDFHUMMUS_NO_DCT` - defines whether to exclude DCT functionality (essentially - not include LibJpeg) from the library. defaults to `FALSE`. when setting `TRUE` the library will not require the existance of LibJpeg however will not be able to decode DCT streams from PDF files. (note that this has no baring on the ability to include JPEG images. That ability does not require LibJpeg given the innate ability of PDF files to include DCT encoded streams).\n- `PDFHUMMUS_NO_TIFF` - defines whether to exclude TIFF functionality (essentially - not include LibTiff) from the library. defaults to `FALSE`. when setting `TRUE` the library will not require the existance of LibTiff however will not be able to embed TIFF images.\n- `PDFHuMMUS_NO_PNG` -  defines whether to exclude PNG functionality (essentially - not include LibPng) from the library. defaults to `FALSE`. when setting `TRUE` the library will not require the existance of LibPng however will not be able to embed PNG images.\n- `USE_BUNDLED` - defines whether to use bundled dependencies when building the project or use system libraries. defaults to `TRUE`. when defined as `FALSE`, the project configuration will look for installed versions of\tLibJpeg, Zlib, LibTiff, FreeType, LibAesgm, LibPng and use them instead of the bundled ones (i.e. those contained in the project). Note that for optional dependencies - LibJpeg, LibTiff, LibPng - if not installed the coniguration will succeed but will automatically set the optional building flags (the 3 just described) according to the libraries avialability. As for required dependencies - FreeType, LibAesgm, Zlib - the configuration will fail if those dependencies are not found. see `USE_UNBUNDLED_FALLBACK_BUNDLED` for an alternative method to deal with dependencies not being found.\n- `USE_UNBUNDLED_FALLBACK_BUNDLED` - Defines an alternative behavior when using `USE_BUNDLED=OFF` and a certain dependency is not installed on the system. If set to `TRUE` then for a dependency that's not found it will fallback on the bundled version of this dependency. This is essentially attempting to find installed library and if not avialable use a bundled one to ensure that the build will succeed.\n- `BUILD_FUZZING_HARNESS` - Enable a fuzz testing target for PDFParser. This makes it possible to runn fuzz tests and debug potential vulnarbilities. read more about this in [here](https://github.com/galkahana/PDF-Writer/wiki/Fuzz-Testing-Of-PDFParser). By default it's `OFF`, set it up with `ON`.\n\nYou can set any of those options when calling the `cmake` command. For example to use system libraries replaced the earlier sequence with:\n\n```bash\ncd build\ncmake .. -DUSE_BUNDLED=FALSE\n```\n\n## Build\n\nOnce you got the project file, you can now build the project. If you created an IDE file, you can use the IDE file to build the project.\nAlternatively you can do so from the command line, again using cmake. \n\nThe following builds the project from its root folder:\n```bash\ncmake --build build [--config release]\n```\n\nThis will build the project inside the build folder. what's in brackets is optional and will specify a release onfiguration build. You will be able to look up the result library files per how you normally do when building with the relevant build environment. For example, for windows, the `build/PDFWriter/Release` folder will have the result PDFWriter file.\n\n## Testing\n\nThis project uses `ctest` for running tests. `ctest` is part of cmake and should be installed as part of cmake installation.\nThe tests run various checks on PDFHummus...and I admit quite a lot of them are not great as unitests as they may just create PDF files without verifying they are good...one uses ones eyes to inspect the test files to do that...or revert to being OK with no exceptions being thrown, which is also good. They are decent as sample code to learn how to do things though 😬.\n\nTo run the project tests (after having created the project files in ./build) go:\n\n```bash\nctest --test-dir build [-C release]\n```\n\nThis should scan the folders for tests and run them.\nConsider appending ` -j22` to the command in order to run tests in parallel to speed things up.\n\n\nYou should be able to see result output files from the tests under `./build/Testing/Output`.\n\n\nNote that `ctest` does NOT build the project. It may fail if there's no previous build, or will not pick up on your changes if you made them\nsince the last build. For This purpose there's an extra target created in the project to make sure the project and test code is built (as well as recreating the output folder to clear previous runs output):\n\n```bash\ncmake --build build --target pdfWriterCheck [--config release]\n```\n\n## Installing\n\nIf you want, you can use the `install` verb of cmake to install a built product (the library files and includes). Use the prefix param to specify where you want the result to be installed to\n\n```bash\ncmake --install build --prefix ./etc/install [--config release]\n```\n\nThis will install all the library files in `./etc/install`. You should see an \"include\" folder and a \"lib\" folder with include files and library files respectively.\n\n# Using PDFHummus in your own project\n\nIf you want to use PDFHummus there are several methods:\n- copying the sources to your project\n- installing the project and including the result in your project\n- using PDFHummus package in your cmake project\n\nNot much to say about the first option. 2nd option just means to follow the installation instructions and then pointing to the resultant lib and include folders to build your project.\n\n3rd option is probably the best, especially if you already have cmake in your project. This project has package definition for `PDFHummus` package, which means you can have cmake look for this package and include it in your project with `find_package`. Then link to the `PDFHummus::PDFWriter` target and you are done. Another option is to do this + allow for fetching the project content from the repo with `FetchContent`. Here's an example from the [PDF TextExtraction project](https://github.com/galkahana/pdf-text-extraction/blob/master/TextExtraction/CMakeLists.txt) of mine:\n\n```cmake\ninclude(FetchContent)\n\nFetchContent_Declare(\n  PDFHummus\n  GIT_REPOSITORY https://github.com/galkahana/PDF-Writer.git\n  GIT_TAG        v4.6.2\n  FIND_PACKAGE_ARGS\n)\nFetchContent_MakeAvailable(PDFHummus)\n\ntarget_link_libraries (TextExtraction PDFHummus::PDFWriter)\n```\n\nThis will either download the project and build it or use an installed version (provided that one exists and has a matching version). \nChange the `GIT_TAG` value to what version you'd like to install. You can use tags, branches, commit hashs. anything goes.\nIncludes are included haha.\n\nYou may consider an alternative form that uses URL instead of GIT_REPOSITORY, like this:\n\n```cmake\ninclude(FetchContent)\n\nFetchContent_Declare(\n  PDFHummus\n  URL https://github.com/galkahana/PDF-Writer/archive/refs/tags/v4.6.2.tar.gz\n  URL_HASH SHA256=0a36815ccc9d207028567f90039785c824b211169ba5da68de84d0c15455ab62\n  DOWNLOAD_EXTRACT_TIMESTAMP FALSE\n  FIND_PACKAGE_ARGS\n)\n\nFetchContent_MakeAvailable(PDFHummus)\n```\n\nThis has the benefit of fetching the archive URL rather than cmake runnig `git clone` on the specified target.\nPDFWriter archives since version v4.6.2 do not include PDFWriterTesting folder and its materials, making it a singificantly smaller download.\nYou can find the archive urls in the Releases area for this repository.\n\n\nNote that when installing PDFHummus with the bundled libraries built (this is the default behvaior which can be changed by setting `USE_BUNDLED` variable to `FALSE`) there are additional targets that PDFHummus includes:\n- PDFHummus::FreeType - bundled freetype library\n- PDFHummus::LibAesgm - bundled aesgm library\n- PDFHummus::LibJpeg - bundled libjpeg library\n- PDFHummus::LibPng - bundled libpng library\n- PDFHummus::LibTiff - bundled libtiff library\n- PDFHummus:::Zlib - bundled zlib library\n\nYou can use those targets in additon or instead of using PDFWriter if this makes sense to your project (like if you are extracting images, having LibJpeg or LibPng around can be useful).\n\n# Packaging PDFHummus for installing someplace else\n\nThe project contains definitions for `cpack`, cmake packaging mechanism. It might be useful for when you want to build PDFHummus and then install it someplace else.\n\nThe following will create a zip file with all libs and includes:\n```\ncd build\ncpack .\n```\n\n# VSCode usage\n\nIf you are developing this project using vscode here's some suggestions to help you:  \n- install vscode C++ extensions:\n    - C/C++\n    - C/C++ Extension Pack\n    - C/C++ Themes\n- install vscode cmake extensions:\n    - Cmake\n    - Cmake Tools\n    - CMake Test Explorder\n\nThis should help you enable testing and debugging the tests in vscode.\n\n\n# More building instructions for when you cant use cmake\n\n\n## iOS\n\nI wrote a post about how to compile and use the library for the iPhone and iPad environments. you can read it [here](http://pdfhummus.com/post/45501609236/how-to-build-iphone-apps-that-use-pdfhummus).\n \n\n## Build insturctions for other scenraios\n\nIt should be quite simple to construct project files in the various building environments (say VS and Xcode) if you want them. Here are some pointers:\n- All the PDFWriter sources are in PDFWriter folder (you can get it by downloading the git project or from the Downloads section).\n- The library is dependent on the dlls/shared libraries of Zlib, LibTiff, LibJpeg, LibPng and FreeType. When linking - make sure they are available.\n- The library should support well both 32 bit and 64 bit environments. It's using standard C++ libraries.\n","funding_links":[],"categories":["PDF","C","For Developers","Libraries"],"sub_categories":["C/C++"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgalkahana%2FPDF-Writer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgalkahana%2FPDF-Writer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgalkahana%2FPDF-Writer/lists"}