{"id":28629763,"url":"https://github.com/fibjs/fib-build","last_synced_at":"2025-06-12T12:13:31.450Z","repository":{"id":257826247,"uuid":"872416953","full_name":"fibjs/fib-build","owner":"fibjs","description":"Build fibjs project to a standalone executable","archived":false,"fork":false,"pushed_at":"2024-11-15T22:20:59.000Z","size":50,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-22T04:18:13.740Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fibjs.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}},"created_at":"2024-10-14T12:01:31.000Z","updated_at":"2025-02-14T03:26:18.000Z","dependencies_parsed_at":"2024-11-11T09:35:50.733Z","dependency_job_id":null,"html_url":"https://github.com/fibjs/fib-build","commit_stats":null,"previous_names":["fibjs/fib-build"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/fibjs/fib-build","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fibjs%2Ffib-build","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fibjs%2Ffib-build/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fibjs%2Ffib-build/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fibjs%2Ffib-build/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fibjs","download_url":"https://codeload.github.com/fibjs/fib-build/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fibjs%2Ffib-build/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259462578,"owners_count":22861514,"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":"2025-06-12T12:13:30.562Z","updated_at":"2025-06-12T12:13:31.436Z","avatar_url":"https://github.com/fibjs.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fib-build\n------------\n\n## Introduction\n\nDeploying applications across various environments is a common challenge in software development. fib-build is a robust tool specifically designed for the fibjs environment, aimed at simplifying this process. It packages application directories into standalone executable files, making deployment and distribution of fibjs applications straightforward. With fib-build, developers can generate a single executable that encapsulates the entire application, including all dependencies and resource files. This eliminates the need for users to install fibjs separately, ensuring that the application can run seamlessly on different systems. By streamlining the deployment process, fib-build enhances efficiency and reduces the complexity associated with managing multiple environments.\n\n## Key Features\n\n### Comprehensive Single Executable File\n\nfib-build excels in creating a comprehensive single executable file that encapsulates the entire fibjs application. This includes not only the core application logic but also all associated resource files and dependencies. By consolidating everything into one executable, fib-build eliminates the need for users to manage complex environmental setups or dependency installations. This feature significantly simplifies the deployment process, allowing users to run the application with a single command, regardless of the underlying system configuration.\n\n### Flexible Custom Base Executable Program\n\nOne of the standout features of fib-build is its flexibility in specifying the base executable program. Users have the option to use the current fibjs executable as the default base file or to specify a different executable tailored to various operating systems and architectures. This customization capability ensures that the packaged application can meet diverse deployment requirements, enhancing its adaptability and usability across different environments. Whether targeting Windows, macOS, or Linux, fib-build provides the tools necessary to create a compatible and efficient executable.\n\n### Robust Cross-Platform Compatibility\n\nWhile it is generally recommended to generate executables on the target operating system to avoid compatibility issues, fib-build supports cross-platform packaging. This feature is particularly beneficial for developers working in macOS environments, as it ensures the stability and compatibility of the executable files on macOS systems. By leveraging fib-build's cross-platform capabilities, developers can streamline their workflow and reduce the overhead associated with managing multiple development environments. This makes fib-build an invaluable tool for teams aiming to deploy applications across various platforms seamlessly.\n\n### Automatic Downgrade for Compatibility\n\nBy default, fib-build merges the executable file and packaged files using embedded resources. However, on certain platforms (such as Linux MIPS, Linux Loong64, Alpine ARM64, etc.), this method may encounter compatibility issues. To address this, fib-build automatically detects these incompatible platforms during the packaging process. When targeting these platforms, it will automatically downgrade to the traditional mode, appending the packaged files to the end of the executable. This ensures better compatibility and reliability across diverse environments, making the deployment process smoother and more robust.\n\n## Installation Steps\n\nBefore starting with fib-build, ensure that fibjs is installed on your system. If it is not installed, please visit the fibjs Installation Guide to set up the environment. Once fibjs is installed, navigate to your project directory and install fib-build using the following command:\n\n```sh\ncd your-project-directory\nfibjs --install fib-build\n```\n\n## Usage\n\nOnce installed, fib-build can be utilized via the command-line interface to package fibjs applications. The basic usage is as follows:\n\n```sh\nfibjs fbuild \u003cfolder\u003e \u003coutfile\u003e\n```\n\n### Parameter Description\n\n- `\u003cfolder\u003e`: Directory containing the fibjs application. This is the root directory where your application code resides. Typically, this is the current directory (`.`), but you can also specify a different directory to handle other projects.\n- `\u003coutfile\u003e`: Required. Path where the executable file should be saved. It is recommended not to save the output file in the project directory to avoid including it in the next packaging process. This specifies the output location and name of the generated executable.\n\n### Optional Parameters\n\n- `--execfile=\u003cfile\u003e`: Specify the base executable file, such as a specific fibjs binary. By default, it uses the executable that is currently running. This option allows you to customize the base binary used for packaging, which can be useful for compatibility with different operating systems or specific versions of fibjs.\n\n- `--legacy`: Use legacy mode to append data to the end of the outfile. This is useful when the embedded resource mode encounters compatibility issues on some platforms. By using the append method for packaging, you can ensure better compatibility across different environments.\n\n- `--gui`: Enable GUI mode. When this option is specified, the packaging process will set the subsystem of the executable to GUI on Windows. On macOS, it will automatically package the application as a bundle. This is particularly useful for applications that require a graphical user interface, ensuring that the executable behaves correctly on different operating systems.\n\n- `--overwrite`: Overwrite the output file if it exists. This option allows you to force the creation of the output file even if a file with the same name already exists, preventing errors related to file existence.\n\nThese parameters ensure that the packaging process is flexible and can be tailored to different deployment needs, making it easier to create optimized and portable fibjs applications.\n\n## Application Examples\n\n### Packaging a Simple fibjs Application\n\nTo package a simple fibjs application, assume you are in the project directory that contains your fibjs application. You want to create an executable named myAppExecutable. You can achieve this by running the following command in your terminal:\n\n```sh\ncd your-project-directory\nfibjs fbuild . ../myAppExecutable\n```\n\nThis command will package the contents of the current directory into an executable file named myAppExecutable.\n\n### Using a Specified fibjs Executable\n\nIn some cases, you might want to use a different fibjs binary as the base for your executable. This can be useful for ensuring compatibility with different operating systems or architectures. To specify a different fibjs binary, use the `--execfile` option:\n\n```sh\ncd your-project-directory\nfibjs fbuild . ../myAppExecutable --execfile=path/to/other/fibjs\n```\nThis command will package the current directory into an executable named myAppExecutable, using the specified fibjs binary located at path/to/other/fibjs.\n\n### Using Legacy Mode\n\nIf you encounter compatibility issues with the embedded resource mode on some platforms, you can use the `--legacy` option to append data to the end of the outfile:\n\n```sh\ncd your-project-directory\nfibjs fbuild . ../myAppExecutable --legacy\n```\n\nThis command will package the contents of the current directory into an executable file named myAppExecutable using the legacy mode.\n\n### Enabling GUI Mode\n\nIf your application requires a graphical user interface, you can use the `--gui` option to enable GUI mode. On Windows, this will set the subsystem of the executable to GUI. On macOS, it will automatically package the application as a bundle. When packaging as a bundle on macOS, `fbuild` will use the basic information from `package.json` to create the bundle. By default, `fbuild` will set a default icon for the bundle. If you want to specify a custom icon, you can add an `icon` field in your `package.json` pointing to your custom icon file.\n\nExample command:\n```sh\ncd your-project-directory\nfibjs fbuild . ../myAppExecutable --gui\n```\nExample package.json:\n```json\n{\n  \"name\": \"myApp\",\n  \"version\": \"1.0.0\",\n  \"description\": \"My fibjs application\",\n  \"main\": \"index.js\",\n  \"author\": \"Your Name\",\n  \"license\": \"MIT\",\n  \"icon\": \"path/to/custom/icon.icns\"\n}\n```\nThis command will package the contents of the current directory into an executable file named myAppExecutable with GUI mode enabled. On macOS, it will create a bundle using the information from `package.json` and set the custom icon specified in the `icon` field.\n\n## File Ignore Rules\n\nDuring the build process, fib-build optimizes the packaging by excluding certain files. Specifically, it ignores:\n\n- Files within directories that start with a dot (.), such as .git or .env.\n- Files located in the fib-build module directory.\n- Files located in the fib-inject module directory.\n\nYou can add an `ignore` field in your `package.json` to specify additional files or directories to be excluded. The `ignore` field can be a string or an array of strings. The patterns used in the `ignore` field follow the same syntax as `.gitignore`.\n\nExample `package.json`:\n```json\n{\n  \"name\": \"myApp\",\n  \"version\": \"1.0.0\",\n  \"description\": \"My fibjs application\",\n  \"main\": \"index.js\",\n  \"author\": \"Your Name\",\n  \"license\": \"MIT\",\n  \"ignore\": [\n    \"path/to/ignore1\",\n    \"path/to/ignore2\",\n    \"*.log\",\n    \"node_modules/\"\n  ]\n}\n```\n\nThis selective exclusion ensures that only essential components are included in the final executable, resulting in a cleaner and more efficient package. By omitting unnecessary files, fib-build creates a lightweight and performant executable ready for deployment across various environments.\n\n## Common Issues and Solutions\n\n### Execution Failure on macOS\n\nIf an executable targeted for macOS is created on non-macOS platforms, it might fail when run on macOS. This issue often arises because the application is not properly signed when packaged on other operating systems. macOS requires applications to be signed to ensure security and integrity. Packaging on a macOS machine ensures that the application is correctly signed, preventing execution failures and security warnings.\n\nIf you encounter this issue, you can try manually signing the application using the following command:\n```sh\ncodesign -s - myAppExecutable\n```\nThis command signs the myAppExecutable, which can help resolve execution failures and security warnings on macOS.\n\n### Output File in Project Directory\n\nIf the `outfile` parameter is set to a path within the project directory, the generated executable will be included in the next packaging process. This can significantly increase the size of the packaged software. To avoid this issue, it is recommended to specify an output path outside the project directory. For example:\n\n```sh\nfibjs fbuild \u003cfolder\u003e ../myAppExecutable\n```\n\nThis ensures that the executable is saved outside the project directory, preventing it from being included in subsequent packaging operations.\n\n### Compression of Application\n\nTo reduce the size of your application, you can inspect the output of fbuild. During the build process, fbuild highlights files larger than 16k in red and files larger than 4k in yellow. By reviewing these larger files, you can determine if they are necessary for runtime. If they are not required, you can delete them and repackage the application. This process helps in creating a more compact and efficient executable.\n\nAdditionally, you can use the `ignore` field in your `package.json` to exclude unnecessary files from the packaging process. The `ignore` field supports pattern matching similar to `.gitignore`, allowing you to specify files or directories to be excluded. This can significantly reduce the size of the final executable.\n\nExample `package.json` with `ignore` field:\n```json\n{\n  \"name\": \"myApp\",\n  \"version\": \"1.0.0\",\n  \"description\": \"My fibjs application\",\n  \"main\": \"index.js\",\n  \"author\": \"Your Name\",\n  \"license\": \"MIT\",\n  \"icon\": \"path/to/custom/icon.icns\",\n  \"ignore\": [\n    \"path/to/ignore1\",\n    \"path/to/ignore2\",\n    \"*.log\",\n    \"node_modules/\"\n  ]\n}\n```\n\nBy specifying unnecessary files in the `ignore` field, you can ensure they are not included in the final package, resulting in a more efficient and smaller executable.\n\n### Platform Compatibility Issues\n\nAlthough fbuild automatically detects platform compatibility and chooses a fallback option to continue packaging, unforeseen compatibility issues may still occur. If the packaged file crashes or does not run as expected, you can manually add the `--legacy` option to force fbuild to use the traditional packaging mode:\n\n```sh\nfibjs fbuild \u003cfolder\u003e ../myAppExecutable --legacy\n```\n\nThis can help resolve issues where the packaged application does not run correctly on certain platforms.\n\n### Performance Considerations\n\nWhile packaging simplifies the deployment process, it is important to note that the initial loading time of the executable might increase due to the need to unpack and deploy files at runtime. To mitigate this, consider optimizing the application’s startup process and minimizing the number of files that need to be unpacked.\n\n## Conclusion\n\nfib-build is a potent tool that eases the deployment process of fibjs applications, enabling developers to effortlessly distribute and execute them in different environments. Following the steps and recommendations provided can optimize the application’s deployment process and enhance its applicability across various environments.\n\nFor more detailed information and advanced features, please refer to the official fibjs documentation. Through these resources, developers can gain a deeper understanding of how to effectively utilize fib-build to enhance the portability and usability of their applications. This guide outlines the steps for installation, usage, and addresses common issues with solutions to ensure a smooth application packaging process. Whether you are a seasoned developer or a newbie to fibjs, understanding the capabilities and features of fib-build will significantly benefit the workflow and distribution of your applications.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffibjs%2Ffib-build","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffibjs%2Ffib-build","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffibjs%2Ffib-build/lists"}