From e04e4746250d0119df8e776833085f2257c9d129 Mon Sep 17 00:00:00 2001 From: Abdulkaiz Khatri <24286590+ful1e5@users.noreply.github.com> Date: Tue, 2 Jul 2024 09:58:12 +0530 Subject: [PATCH] docs: Update build from source instruction --- README.md | 177 ++++++++++++++++++++++++------------------------------ 1 file changed, 79 insertions(+), 98 deletions(-) diff --git a/README.md b/README.md index d31a5cd..0dfcb6d 100644 --- a/README.md +++ b/README.md @@ -4,22 +4,17 @@ Extended KDE cursor, Highly inspired on **KDE Breeze** for `Windows` and `Linux` [![build](https://github.com/ful1e5/BreezeX_Cursor/actions/workflows/build.yml/badge.svg)](https://github.com/ful1e5/BreezeX_Cursor/actions/workflows/build.yml) -## BreezeX needs your Input +## Notes -Until 2021 my cursors projects were well funded by [pling.com](https://www.pling.com) but since the -[pling-factor](https://www.pling.com/terms/payout) on the website has decreased and monthly payments -are <500$, It is now dependent on community funding and sponsorships. If you want to help me to maintain -BreezeX and my other open source projects actively, consider sponsoring my work on [GitHub Sponsor](https://github.com/sponsors/ful1e5) -or DM me on [Twitter](https://twitter.com/ful1e5) if your company would like to support my projects, -I will gladly look into it and post your avatar in the project's README. +- All cursor's SVG files are found in [svg](./svg) directory or you can also find them on [Figma](https://www.figma.com/design/Uo4LeHvFUPDgoqLjnFc1LB/BreezeX?node-id=2620-3&t=7QqTBQ4MOqXONrGI-1). -I appreciate all the wonderful people who patronize and sponsoring my work. + -## Sponsors +![shoutout-sponsors](https://sponsor-spotlight.vercel.app/sponsor?login=ful1e5) - - -N/A +- **2024-07-01**: [b9d526d](https://github.com/ful1e5/BreezeX_Cursor/commit/b9d526df48ac582ea80b7b6329da903f2760e046) Partitioned cursor build configuration into multiple files according to platform: + `build.toml` -> `configs/win_lg.build.toml`, `configs/win_rg.build.toml`, `configs/win_xl.build.toml`, `configs/x.build.toml`. --- @@ -27,14 +22,12 @@ N/A ![BreezeX Light](https://imgur.com/tmKu1vC.png) ![BreezeX Black](https://imgur.com/kzLufkT.png) -> **Note** -> All cursor's `.svg` files are found in [svg](./svg) directory or you can also find them on -> [Figma](https://www.figma.com/file/Uo4LeHvFUPDgoqLjnFc1LB/BreezeX?node-id=0%3A1). - ## Cursor Sizes ### Xcursor Sizes: +16 +20 22 24 28 @@ -50,27 +43,30 @@ N/A ### Windows Cursor Size: -- 16x16 - Small -- 24x24 - Regular -- 32x32 - Large -- 48x48 - Extra Large +| size | Regular (× ²⁄₃) | Large (× ⁴⁄₅) | Extra-Large (× 1) | +| ---: | --------------: | ------------: | ----------------: | +| 32 | 21.333 → 22 | 25.6 → 26 | 32 | +| 48 | 32 | 38.4 → 39 | 48 | +| 64 | 42.666 → 43 | 51.2 → 52 | 64 | +| 96 | 64 | 76.8 → 77 | 96 | +| 128 | 85.333 → 86 | 102.4 → 103 | 128 | -## Colors: +## Colors ### BreezeX Dark -- Base Color - `#4D4D4D` (Breeze) -- Outline Color - `#FFFFFF` (White) +- Outline Color - `#FFFFFF` (White) +- Base Color - `#4D4D4D` (Breeze) ### BreezeX Light -- Base Color - `#FFFFFF` (White) -- Outline Color - `#4D4D4D` (Breeze) +- Outline Color - `#4D4D4D` (Breeze) +- Base Color - `#FFFFFF` (White) ### BreezeX Black -- Base Color - `#000000` (Black) -- Outline Color - `#FFFFFF` (White) +- Outline Color - `#FFFFFF` (White) +- Base Color - `#000000` (Black) ## How to get it @@ -125,79 +121,71 @@ Run the `uninstall.bat` script packed with the `.zip` archive ## Build From Source -#### Notes - -- BreezeX build configuration and cursor hotspot settings are bundled in the `build.toml` file. -- Check out the scripts section in [package.json](./package.json) to see how we build the cursor theme, - excluding the render scripts. They are useful for converting `.svg` files to `.png` files. -- yarn is optional, For building XCursors and Windows cursors from `.png` files or resizing them - you don't need that. If you want to develop/modify BreezeX's colors, and bitmaps, or generate a png - file from a svg, Then you can use yarn because bitmapper is written in TypeScript. -- Since BreezeX variants are designed similarly, they share the same hotspot settings so a - single configuration file `build.toml` is responsible for building all variants. Due to this, you will have - to change the following options in `ctgen` to build the appropriate variant: - - **-d**: bitmaps directory - - **-n**: The name you want to give to the generated theme. - - **-c**: Theme comment. - - See `ctgen --help` for all available options. - -### Build prerequisites +### Prerequisites -- Python version 3.7 or higher -- [clickgen](https://github.com/ful1e5/clickgen)>=2.1.2 (`pip install clickgen`) -- [yarn](https://github.com/yarnpkg/yarn) +- Python version 3.7 or higher +- [clickgen](https://github.com/ful1e5/clickgen)>=2.2.5 (`pip install clickgen`) +- [yarn](https://github.com/yarnpkg/yarn) ### Quick start -1. Install [build prerequisites](#build-prerequisites) on your system +1. Install [build prerequisites](#prerequisites) on your system 2. `git clone https://github.com/ful1e5/BreezeX_Cursor` -3. `cd BreezeX_Cursor && yarn build` -4. See [Installing BreezeX Cursor](#installing-breezex-cursor). +3. `cd BreezeX_Cursor` +4. `yarn install` +5. `yarn generate` +6. See [Installing BreezeX Cursor](#installing-breezex-cursor). + +### Getting Started + +Once you have the [build prerequisites](#prerequisites) installed, You can personalize colors, +customize sizes, change target platforms, and more. This process involves using external tools, +as this repository only contains SVG files and configuration for these tools: + +- [cbmp](https://github.com/ful1e5/cbmp): Used for customizing colors and generating PNG files. +- [ctgen](https://github.com/ful1e5/clickgen): Used for customizing sizes and building XCursor and Windows Cursors. -### Building +You can refer to the README of each tool for more information on their command-line options. -> **Note** -> Bitmaps are already generated in the `bitmaps` directory and **managed by the maintainer** -> (do not edit them directly). +#### Crafting Your BreezeX Cursor -First make sure you installed the [build prerequisites](#build-prerequisites). -Now that you have the dependencies, you can try build individual themes from bitmaps and -customize sizes, target platform, and etc. with the `ctgen` CLI (packed with `clickgen`). +The process of creating custom cursor themes involves two main steps: -#### `yarn build` aberration +1. Rendering SVG files to PNG files. +2. Building cursor themes from PNG files. -Here are the default commands we used to build the BreezeX's variants and packed them into `yarn build`: +#### Customize Colors + +`cbmp` provides three options for changing colors: + +1. `-bc`: Base color, which replaces the `#00FF00` color in the SVG. +2. `-oc`: Outlined color, which replaces the `#0000FF` color in the SVG. +3. `-wc` (optional): Watch Background color, which replaces the `#FF0000` color in the SVG. ```bash -ctgen build.toml -d 'bitmaps/BreezeX-Dark' -n 'BreezeX-Dark' -c 'BreezeX Dark cursors.' -ctgen build.toml -d 'bitmaps/BreezeX-Light' -n 'BreezeX-Light' -c 'BreezeX Light cursors.' -ctgen build.toml -d 'bitmaps/BreezeX-Black' -n 'BreezeX-Black' -c 'BreezeX Black cursors.' +npx cbmp [...] -bc '' -oc '' -wc '' ``` -Afterwards, the themes can be found in the `themes` directory. +Alternatively, you can provide a JSON configuration file to render SVG files, which contains a sequence of `cbmp` commands: -#### Customize Sizes +```bash +npx cbmp render.json +``` -> **Note** -> You can change the cursor size up to 200 because pngs are rendered with 200x200. -> If the cursor is resized by more than rendered png size, the final cursor will be blurred. +#### Customize Sizes ##### Customize Windows Cursor size To build Windows cursor with size `16`: -> **Warning** -> Windows cursor supports only one size, if multiple sizes are given with `-s` the first size will -> be considered in build. - ```bash -ctgen build.toml -s 16 -p windows -d 'bitmaps/BreezeX-Light' -n 'BreezeX-Light' -c 'White BreezeX cursors with size 16' +ctgen build.toml -s 16 -p windows -d 'bitmaps/BreezeX-Dark' -n 'BreezeX-Dark' -c 'Extended Breeze XCursors with size 16' ``` You can also customize output directory with `-o` option: ```bash -ctgen build.toml -s 16 -p windows -d 'bitmaps/BreezeX-Light' -o 'out' -n 'BreezeX-Light' -c 'White BreezeX cursors with size 16' +ctgen build.toml -s 16 -p windows -d 'bitmaps/BreezeX-Dark' -o 'out' -n 'BreezeX-Dark' -c 'Extended Breeze Windows Cursors with size 16' ``` ##### Customize XCursor size @@ -205,43 +193,27 @@ ctgen build.toml -s 16 -p windows -d 'bitmaps/BreezeX-Light' -o 'out' -n 'Breeze To build XCursor with size `16`: ```bash -ctgen build.toml -s 16 -p x11 -d 'bitmaps/BreezeX-Light' -n 'BreezeX-Light' -c 'White BreezeX cursors with size 16' +ctgen build.toml -s 16 -p x11 -d 'bitmaps/BreezeX-Dark' -n 'BreezeX-Dark' -c 'Extended Breeze XCursors with size 16' ``` You can also assign multiple sizes to `ctgen` for XCursors build: ```bash -ctgen build.toml -s 16 24 32 -p x11 -d 'bitmaps/BreezeX-Light' -n 'BreezeX-Light' -c 'White BreezeX cursors with size 16' -``` - -#### Customize Colors - -To customize BreezeX's color you have to install node dependencies with `yarn install` command. -After installing dependencies you can customize the colors via `npx cbmp` Node CLI App which packed with -[cbmp](https://github.com/ful1e5/cbmp) node package. - -##### `yarn render` aberration - -Here are the default commands we used for generating the BreezeX's bitmaps and packed them into `yarn render`: - -```bash -npx cbmp -d 'svg' -n 'BreezeX-Dark' -bc '#4D4D4D' -oc '#FFFFFF' -npx cbmp -d 'svg' -n 'BreezeX-Light' -bc '#FFFFFF' -oc '#4D4D4D' -npx cbmp -d 'svg' -n 'BreezeX-Black' -bc '#000000' -oc '#FFFFFF' +ctgen build.toml -s 16 18 24 32 -p x11 -d 'bitmaps/BreezeX-Dark' -n 'BreezeX-Dark' -c 'Extended Breeze XCursors with multi-sizes' ``` #### Examples -Lets generate modern BreezeX with green base color and black outline: +Lets generate BreezeX Cursor with green and black colors: ```bash -npx cbmp -d 'svg' -n 'BreezeX-Hacker' -bc '#00FE00' -oc '#000000' +npx cbmp -d 'svg' -o 'bitmaps/BreezeX-Hacker' -bc '#00FE00' -oc '#000000' ``` After rendering custom color you have to build cursor through `ctgen`: ```bash -ctgen build.toml -d 'bitmaps/BreezeX-Hacker' -n 'BreezeX-Hacker' -c 'Green and black BreezeX cursors.' +ctgen build.toml -d 'bitmaps/BreezeX-Hacker' -n 'BreezeX-Hacker' -c 'Green and Black BreezeX cursors.' ``` Afterwards, Generated theme can be found in the `themes` directory. @@ -249,31 +221,40 @@ Afterwards, Generated theme can be found in the `themes` directory. ###### BreezeX Gruvbox ```bash -npx cbmp -d 'svg' -n 'BreezeX-Gruvbox' -bc '#282828' -oc '#EBDBB2' +npx cbmp -d 'svg/original' -o 'bitmaps/BreezeX-Gruvbox' -bc '#282828' -oc '#EBDBB2' ctgen build.toml -d 'bitmaps/BreezeX-Gruvbox' -n 'BreezeX-Gruvbox' -c 'Groovy BreezeX cursors.' ``` ###### BreezeX Solarized Dark ```bash -npx cbmp -d 'svg' -n 'BreezeX-Solarized-Dark' -bc '#002b36' -oc '#839496' +npx cbmp -d 'svg/original' -o 'bitmaps/BreezeX-Solarized-Dark' -bc '#002b36' -oc '#839496' ctgen build.toml -d 'bitmaps/BreezeX-Solarized-Dark' -n 'BreezeX-Solarized-Dark' -c 'Solarized Dark BreezeX cursors.' ``` ###### BreezeX Solarized Light ```bash -npx cbmp -d 'svg' -n 'BreezeX-Solarized-Light' -bc '#839496' -oc '#002b36' +npx cbmp -d 'svg/original' -o 'bitmaps/BreezeX-Solarized-Light' -bc '#839496' -oc '#002b36' ctgen build.toml -d 'bitmaps/BreezeX-Solarized-Light' -n 'BreezeX-Solarized-Light' -c 'Solarized Light BreezeX cursors.' ``` ###### BreezeX Dracula ```bash -npx cbmp -d 'svg' -n 'BreezeX-Dracula' -bc '#282a36' -oc '#f8f8f2' +npx cbmp -d 'svg/original' -o 'bitmaas/BreezeX-Dracula' -bc '#282a36' -oc '#f8f8f2' ctgen build.toml -d 'bitmaps/BreezeX-Dracula' -n 'BreezeX-Dracula' -c 'Dracula BreezeX cursors.' ``` +## Testing Cursor + +There are several websites that allow you to test your cursor states by hovering over buttons. This can be very useful when developing or verifying the behavior of a cursor. The following websites cover many of the most commonly used cursors, although they may not include all available options. + +- [Cursor-Test](https://vibhorjaiswal.github.io/Cursor-Test/) +- [Mozilla CSS Cursor](https://developer.mozilla.org/en-US/docs/Web/CSS/cursor) + +For a blueprint for creating XCursors, you may also want to refer to [Cursor-demo](https://wiki.tcl-lang.org/page/Cursor+demo). + ## Bugs Bugs should be reported [here](https://github.com/ful1e5/BreezeX_Cursor/issues) on the Github issues page.