Skip to content

Commit

Permalink
Application packager scripts has been added in docs (#305)
Browse files Browse the repository at this point in the history 
* Added docs for build scripts for creating portable application packages

* links added for docs

* Update overview.md

---------

Co-authored-by: Shalitha Suranga <shalithasuranga@gmail.com>
  • Loading branch information
@viralgupta @shalithasuranga
viralgupta and shalithasuranga authored Mar 18, 2024
1 parent 0877df4 commit c755b9b
Showing 1 changed file with 113 additions and 15 deletions.
128 changes: 113 additions & 15 deletions docs/distribution/overview.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,31 +37,129 @@ the resource file. For example, if you need to make an application package for `
and the `resources.neu` file. The `resources.neu` contains all application resources, so, double click on the binary and check whether
the resource file is not corrupted.

## Creating a portable application package
## Creating portable application packages using build scripts

The [`hschneider/neutralino-build-scripts`](https://github.com/hschneider/neutralino-build-scripts/) community project offers pre-developed build scripts for generating platform-specific application bundles. For example, it generates a standard app structure on GNU/Linux by generating `.desktop` file with app icon by also providing a shell script to install the app.

The following guides are not documented yet.

- [Creating a portable application package for Linux](#)
- [Creating a portable application package for macOS](#)
- [Creating a portable application package for Windows](#)
Clone the scripts to your root directory of your app folder to get started with Neutralinojs build scripts:

```bash
git clone https://github.com/hschneider/neutralino-build-scripts.git build-scripts
```

### Creating a portable application package for macOS
Install jq, which is required for parsing JSON files:

The `neu build` process creates a binary file for macOS, but that file can not be executed by a double-click action on macOS as a normal application.
The following steps shows how to create a simple double-clickable executable on macOS.
```bash
# On macOS:
brew install jq
# On Linux or Windows/WSL:
sudo apt-get install jq
```

1. Open Terminal.
2. Navigate to the `/dist/myapp` directory:
3. Change the binary file type to `.app` file type:
Update `neutralino.config.json` file with build scripts configuration as follows:

```json
"buildScript": {
"mac": {
"architecture": ["x64", "arm64", "universal"],
"minimumOS": "10.13.0",
"appName": "myapp",
"appBundleName": "myapp",
"appIdentifier": "com.marketmix.ext.bun.demo",
"appIcon": "resources/icons/icon.icns"
},
"win": {
"architecture": ["x64"],
"appName": "myapp",
"appIcon": "resources/icons/icon.ico"
},
"linux": {
"architecture": ["x64", "arm64", "armhf"],
"appName": "myapp",
"appIcon": "resources/icons/icon.png",
"appPath": "/usr/share/myapp",
"appIconPath": "/usr/share/myapp/icon.png",
"appIconLocation": "/usr/share/myapp/icon.png"
}
}
```
mv <mac_binary> <mac_binary>.app

### Generating an application bundle for macOS

You can generate a new application bundle for macOS by running the following command:

```bash
./build-mac.sh
```
4. Give the app file the required execution permissions:

The build is created in the `./dist` folder.

The `buildScript/mac` JSON segment in the config-file contains the following fields:

| Key | Description |
| ------------- | ------------------------------------------------------------ |
| architecture | This is an array of the architectures, you want to build. In our example we build all 3 architectures. |
| minimumOS | The minimum macOS version. |
| appName | The app-name as displayed in the Finder. |
| appBundleName | The macOS app-bundle name. |
| appIdentifier | The macOS app-identifier. |
| appIcon | Path to the app-icon in **.icns** format. If only the filename is submitted, the file is expected in the project's root. |


Visit the [build scripts official documentation](https://github.com/hschneider/neutralino-build-scripts/#build-for-macos) for more details.

### Generating an application bundle for Windows

You can generate a new application bundle for Windows by running the following command:

```bash
./build-win.sh
```
chmod +x <mac_binary>.app

The build is created in the `./dist` folder.

> You can now run install `install-icon.cmd` to set the app icon as specifed in config file. This script required you to have [Resource Hacker](https://www.angusj.com/resourcehacker/) installed on your machine.
The `buildScript/win` JSON segment in the config-file contains the following fields:

| Key | Description |
| ------------ | ------------------------------------------------------------ |
| architecture | This is an array of the architectures, you want to build. Because Neutralino currently only support 'x64', you should leave this untouched. |
| appName | The app-name as displayed in the File Explorer, with or without .exe-suffix. |
| appIcon | Path to the app-icon in **.ico** format. If only the filename is submitted, the file is expected in the project's root. The icon is copied from this path into the app-bundle. To apply the icon to the executable file, you'll have to run **[Resource Hacker](https://www.angusj.com/resourcehacker/)** from a Windows machine. To do so, just double-click **install-icon.cmd** in the app-bundle. |


:::note
You can add custom code to `preproc-win.sh` and `postproc-win.sh` if you need run it before or after the build process.
:::

Visit the [build scripts official documentation](https://github.com/hschneider/neutralino-build-scripts/#build-for-windows) for more details.

### Generating an application bundle for Linux

You can generate a new application bundle for GNU/Linux by running the following command:

```bash
./build-linux.sh
```

Now you can execute the app by double-click.
All build targets are created in the `./dist` folder.

> Calling `sudo ./install.sh` from your build folder automatically installs the app to the locations you defined.
The `buildScript/linux` JSON segment in the config-file contains the following fields:

| Key | Description |
| ------------ | ------------------------------------------------------------ |
| architecture | This is an array of the architectures, you want to build. In our example we build all 3 architectures. |
| appName | The app-name as displayed in the File Explorer. |
| appIcon | Path to the app-icon in **.png or .svg** format. If only the filename is submitted, the file is expected in the project's root. The icon is copied from this path into the app-bundle. Example: `resources/icons/icon.png` |
| appPath | The path of application directory in system where the source files will live **after** installing without the executable name and without ending slash. Example: `/usr/share/myapp` |
| appIconPath | This is path to application icon **after** the application has been installed in the Linux system. This path is written to the .desktop-file. Example: `/usr/share/myapp/icon.png` |
| appIconLocation | Same as appIconPath. |

Visit the [build scripts official documentation](https://github.com/hschneider/neutralino-build-scripts/#build-for-linux) for more details.

## Creating application installers

Expand Down

0 comments on commit c755b9b

Please sign in to comment.