diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ae9aef0 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,63 @@ +# Contributing + +Thank you for your interest in helping Cartero grow! This document will +provide information and tips on how to help the project. + +## Contributing with code + +This project is highly appreciative of contributions. If you know about Rust, +GTK or the GNOME technologies and want to help during the development, you can +contribute if you wish. [Fork the project][fork] and commit your code. + +Some checklist rules before submitting a pull request: + +- **Use a feature branch**, do not make your changes in the trunk branch + directly. + +- **Rebase your code** and make sure that you are working on top of the most + recent version of the trunk branch, in case something has changed while you + were working on your code. + +- **Update the locales** if you changed strings. The ninja target that you are + looking for is called `cartero-update-po` (such as `ninja -C build +cartero-update-po`). Don't worry, you don't have to translate the strings by + yourself, but make sure that the new templates are added to the .po and .pot + files. + +- **Use the pre-commit hook**. The pre-commit hook will validate that your code + is formatted. It should be automatically configured if you run Meson in + development mode (`-Dprofile=development`), but you can install it on your + own or run `hooks/pre-commit.hook`. + +The project is starting small, so if you want to do something big, it is best +to first start a discussion thread with your proposal in order to see how to +make it fit inside the application. + +This project is published with the GNU General Public License 3.0 or later. +Therefore, your contribution will be checked out into the repository under that +license. **Make sure you are comfortable with the license before contributing**. +Specifically, while you retain copyrights of your contribution, you acknowledge +that you allow anyone to use, study or distribute any code you write under the +terms of that license. + +This application is not affiliated with the GNOME project, but we follow the +[GNOME Code of Conduct][coc] anyway as a guideline and we expect you to follow +it when interacting with the repository. + +## Contributing with translations + +Do you want to use Cartero in your language? We are using [Weblate][weblate] +to coordinate and translate comfortably this project using a web interface. +Make an account and start proposing strings and they will be added to the +application. That will also entitle you as a contributor! + +## Contributing with feedback + +Cartero is still getting new features, and hopes to be as useful as it can be. +Found a bug or something is wrong? Report it. An use case you are missing? +Report it. Show us how you integrate Cartero on your workflow so that we can +build our diverse list of use cases. + +[fork]: https://github.com/danirod/cartero/fork +[weblate]: https://hosted.weblate.org/projects/cartero/ +[coc]: https://conduct.gnome.org diff --git a/HACKING.md b/HACKING.md index f50f848..90b0e13 100644 --- a/HACKING.md +++ b/HACKING.md @@ -2,101 +2,83 @@ Some additional instructions for people interested in running cartero. -## "Meson sucks, stick with Cargo" +## TL;DR -I don't disagree with this statement, in fact. I fail to see exactly how is -Meson better than CMake when it does the same tasks, but sometimes worse, since -Meson is not as flexible and extensible as CMake is, and this is seen as how -fragile is the integration between Meson and Rust. +This project makes use of Meson, whether you like it or not. If you are used +to GNOME app development, you might already like it. Otherwise, you'll have to +accept it. -Meson is as opinionated on how to build a program as Cargo is. Meson will call -Cargo when it is time to build the executable file by just issuing the `cargo -build` external command, but the build script still has to copy a lot of files -so that both tools can coexist without shilling at each other publicly on your -terminal. +However, treating this source code workspace as a standard Rust project makes +sense because then you can use autocompletion and other Rust tools. Therefore, +to make things easier, there is an aux script that you can use to quickly rebuild +the application data files (resource bundles, translations, icons, GLib schemas) +and move them to the `target/` directory: -This project is making use of it because of two reasons: - -* Because there is actually more than Rust for this project and Meson knows - how to compile the resource bundles, update the locales and generate the - desktop files for Cartero. - -* Because it ticks a checkbox. - -To be honest, if you are not a try-hard GNOME developer, you will find casually -hacking applications based on the GNOME stack difficult and cumbersome because -some of the following reasons mean that "installing" the app, or at least the -data files (/usr/share), is necessary to run the program. - -* Many applications will make use of the GSettings framework to load and store - application settings, and GSettings require the GSchemas to be installed - globally in order to use them. - -* Some features, such as application notifications, may not work at all unless - the application is installed and thus recognised by the GNOME notifications - framework. - -* Some applications insist on using absolute and hardcoded locations when - loading translation files and GResource bundles, such as always trying to load - from $prefix/share. Therefore, unless the application is installed, the file - system hierarchy will not be fully set. - -A valid answer to these complains would be "just compile and debug a Flatpak", -but this will not be the taste of some people and I understand that. - -My suggestion however is to just use a local installdir such as $PWD/install, -and just run `ninja install` into your prefix as part of the compilation -process. This doesn't require root privileges (DO NOT SUDO WHILE TESTING OR -RUNNING CARTERO FOR GOD'S SAKE) and it can be easily cleaned with `rm -rf -install` later. +``` +build-aux/cargo-build.sh +``` -### Alternative build script +You should check the contents of the script before running it. But it will +precompile parts of the application using meson and the run `cargo build`. You +can then call `cargo r`, `cargo t` or whatever you plan on doing with the code. -Precisely, that's what my alternative build scripts do. +## "But Meson sucks, stick with Cargo!" -**build-aux/meson-build.sh** is a script that doesn't do anything different than -what the README.md file indicates, but it automates it in order to do it very -quick. So running **build-aux/meson-build.sh** will run `meson setup` and `ninja -&& ninja install` for you, using the following paths: +I don't disagree with this statement, in fact. I feel like Meson is not as +flexible as other build systems like CMake, specially when it comes to creating +and running custom commands. This has the effect of making the integration +between Rust and Meson very fragile. -* It will build the application into $PWD/build. -* It will install the application to $PWD/install. +Meson is an opinionated tool. However, Cargo is also a very opinionated tool. +Meson will invoke Cargo when it is time to build the executable file by just +issuing the `cargo build` external command, but the build script still has to +copy a lot of files to Meson's build directory so that both tools can coexist +without shilling at each other publicly on your terminal. -So a quick workflow for hacking Cartero while using the script would be: +Why does Cartero use Meson? -```sh -build-aux/meson-build.sh && install/bin/cartero -``` +* Because there is actually more than Rust for this project and Meson knows + how to compile the resource bundles, update the locales and generate the + desktop files for Cartero. -As you probably have noticed, Meson sucks, and sometimes it will not detect that -the GResource file has to be recompiled, despite my attempts to make sure that -every target in my meson.build files has dependencies properly set. +* Because it ticks a checkbox when it comes to aligning to the GNOME guidelines, + which this project intends to follow, even though Cartero supports a wide + variety of operating systems and desktop environments. -If you notice while running meson-build.sh that the application crashes or does -not detect the changes that you made to the user interface files, my suggestion -is to just run `rm -rf build/data` and recompile. Meson should see that the -resource file is missing and it should create it from scratch. +Due to these things, switching to `build.rs` will not fix things at all, it +will just turn the tables upside down, making Rust code easier to build at the +expense of making every non-Rust resource way more difficult to compile. -### But I want to use cargo build +## But I want to use cargo build I know, and it makes a lot of sense, because chances are that you are using a -text editor or IDE (this includes GNOME Builder) with some dveloper tools such +text editor or IDE (this includes GNOME Builder) with some developer tools such as rust-analyzer, and this directory will probably want to use `target` to do its stuff and provide completions. -As long as you have the dependencies in your system (GTK, SourceView5...), you -should be able to just `cargo build` the application and **it has to compile**. -If `cargo build` does not work, that's a bug. +`cargo build` will just care about compiling the application provided that you +have every system dependency installed (GTK, GtkSourceView...). It doesn't care +about whether the resources or translations have been bundled. + +Theferore, `cargo build` has to work anyway. You should be able to just run +`cargo build` in a clean workspace and it has to compile the application. +**If it doesn't work, then that's a bug.** However, since you need the resource bundle and the translation files, `cargo run` will not work unless you place them in your target directory as well, as I tried to explain above. -The good thing is that Cargo actually builds your application into a -subdirectory of `target`, such as `target/debug` or `target/release`. In this -case, the `debug` and `release` directories act as the bindir for cartero, so -all you have to do is to create a `target/share` directory, place all the -datafiles in `target/share`, and that's it. +Cartero will follow the standard UNIX directory standards. Therefore, it expects +to be running inside some kind of `bindir` and by default it will assume that the +datafiles are in `../share`. + +In normal circunstances, your bindir will be `/usr/bin` and therefore the datafiles +will be in `/usr/bin/../share => /usr/share`. + +However, because Cargo will build the application into a subdirectory inside of +`target`, whether that's `target/debug` or `target/release`, this directory can +act as a valid `bindir`. If the datafiles are placed into `target/share`, then +Cartero has to run. **And that is exactly what build-aux/cargo-build.sh** does. So if you want to use `cargo build` and `cargo run`, just use `build-aux/cargo-build.sh`, which @@ -109,25 +91,6 @@ to craft a valid pkgdatadir. It will then proceed to deploy them into build-aux/cargo-build.sh && cargo run ``` -Just the same as above, if you notice that your user interface files are not -updating, just run `rm -rf build/data` and try to compile the application again. - -### Two CARGO_HOMEs? - -One thing to point out is that Meson uses its own vendored CARGO_HOME directory -and it compiles into a different target directory inside build. Therefore, if -you mix both pipelines, you will probably see more often Cargo downloading and -compiling dependencies. - -I think that the vendoring process made by Meson is correct and useful and thus -I do not see this as a drawback. I'm just pointing this out because waiting for -Cargo to compile dependencies suck and mixing `cargo build` with `meson` will -make you wait more often. - -### Absolute directories - -Just as a note: Cartero does not make use of absolute paths. You should be able -to run the application from any location, as long as there is a separate bindir -and datadir. I placed this requirement for the future, since I want a Microsoft -Windows installer to exist and I cannot just run cargo build inside the -installer. (Or can I?!) +If you notice that your user interface files are not updating or your translations +are not being picked up, you can just run `rm -rf build/data` or `rm -rf target/share` +and try again. (If you have to do this a lot, this is probably a bug.) diff --git a/README.md b/README.md index 4ae2266..5e0324f 100644 --- a/README.md +++ b/README.md @@ -12,13 +12,13 @@ test web APIs and perform all kind of HTTP requests to web servers. It is compatible with any REST, SOAP or XML-RPC API and it supports multiple request methods as well as attaching body payloads to compatible requests. -Features: +**Features:** - Loads and saves to plain Git-friendly TOML files, so that you can own your data. - Customization and modification of the request headers and body payloads. - Variable binding for API keys and other secret information. -## Motivation +**Motivation:** This project exists because there aren't many native graphical HTTP testing applications / graphical alternatives to cURL that are fully free software, and @@ -29,115 +29,45 @@ some unwanted artificial intelligence at users. ## Download +### Get it from Flathub + Get it on Flathub -You can also download a version for Windows or macOS. +### Download for your OS -| | Platform | Latest version | -| ----------------------------- | --------------------- | ------------------------------------ | -| ![Windows](doc/windows.png) | Windows, x86_64 | [v0.1.4 (installer)][windows-x86_64] | -| ![macOS](doc/macos.png) | macOS, Apple Sillicon | [v0.1.4 (.dmg)][macos-sillicon] | -| ![macOS](doc/macos.png) | macOS, Intel | [v0.1.4 (.dmg)][macos-intel] | -| ![AppImage](doc/appimage.png) | AppImage, x86_64 | [v0.1.4 (AppImage)][appimage-x86_64] | +| Windows | macOS | AppImage | +| ------- | ----- | --- | +| ![Windows](doc/windows.png) | ![macOS](doc/macos.png) | ![AppImage](doc/appimage.png) | +| [x64, installer][windows-x86_64]
[x64, portable][windows-portable-x86_64] | [Apple Sillicon][macos-sillicon]
[Intel 64-bit][macos-intel] | [amd64][appimage-x86_64] | -## Building +### Get it from your package manager -### Flatpak +Note: distributions in package managers are maintained by the community. While I am open to provide help and communication with maintainers of those ports, outdated versions and other packaging issues should be reported first to the package manager or to the package maintainer, not upstream. -Install the runtime: +[![Packaging status](https://repology.org/badge/vertical-allrepos/cartero.svg)](https://repology.org/project/cartero/versions) -```sh -flatpak install --user org.gnome.Sdk//46 org.freedesktop.Sdk.Extension.rust-stable//23.08 -``` +Additional platforms: -Install the Flatpak, possibly passing the `--user` parameter. - -```sh -flatpak-builder --user --install flatpak_app build-aux/es.danirod.Cartero.json -``` - -You will find Cartero in your application launcher, or you can launch it with -`flatpak run es.danirod.Cartero`. - -### Homebrew +
+ macOS: install via Homebrew To install Cartero from this cask, simply add this repository as a tap. -```sh +``` brew tap SoloAntonio/cartero ``` Now you can install any version hosted as cask with -```sh -brew install --cask cartero -``` - -### Meson - -Use this to build the application outside of a Flatpak image. Note that this method should -only be used by power users, to package the application on build scripts for rolling-release -distributions, or for development purposes. - -Currently, to build the application you'll have to make sure that the required -libraries are installed on your system. - -- glib >= 2.72 -- gtk >= 4.14 -- gtksourceview >= 5.4 -- libadwaita >= 1.5 - -Make sure that you have Meson in your system. For instance, - -```sh -sudo apt install meson -sudo dnf install meson -sudo pacman -S meson -``` - -Then use the following commands to build and install the application - -```sh -meson setup build -ninja -C build -ninja -C build install -``` - -To avoid installing system-wide the application, you can use a prefix: - -```sh -meson setup build --prefix=/usr -ninja -C build -ninja -C build install ``` - -**If you plan on contributing to the project**, use the development profile. - -```sh -meson setup build -Dprofile=development +brew install --cask cartero ``` +
-It will also configure a Git hook so that the source code is checked prior to -authoring a Git commit. The hook runs `cargo fmt` to assert that the code is -formatted. Read `hooks/pre-commit.hook` to inspect what the script does. - -### Cargo (Rust) - -This may be the preferred approach if you use rust-analyzer and tools like -that, because Meson uses a separate target directory, and you might prefer to -use the standard target/ directory. - -You can use `cargo build` and `cargo run` to build and run the project -executable, but you will still need to use Meson to build the data files -(GSettings schema files, Gio resource files, gettext translations...). - -**You should use `build-aux/cargo-build.sh`**. It wraps `cargo build`, but also -compiles the data files and copies them in `target/share`, so that during -application startup those files can be picked. - -### Nix/NixOS +
+ NixOS: manually add the flake Use this approach to install, build or try cartero on a nixos system. Instructions assume you're using a flakes nixos system, but you could install it in a regular @@ -195,65 +125,70 @@ home.packages = with pkgs; [ > [!NOTE] > You may need to reboot the system or relogin to be able to see cartero on your launcher -## Contributing +
-> 🐛 This project is currently a larva trying to grow. Do you want to get in? -> Take a seat! +## Building -### Contributing with code +Currently, to build the application you'll have to make sure that the required +libraries are installed on your system. -This project is highly appreciative of contributions. If you know about Rust, -GTK or the GNOME technologies and want to help during the development, you can -contribute if you wish. [Fork the project][fork] and commit your code. +- glib >= 2.72 +- gtk >= 4.14 +- gtksourceview >= 5.4 +- libadwaita >= 1.5 +- openssl >= 1.0 -Some checklist rules before submitting a pull request: +For a successful build, will also need the following packages installed in your system: **meson**, **ninja**, **rust** and **gettext**. -- **Use a feature branch**, do not make your changes in the trunk branch - directly. +Then use the following commands to build and install the application -- **Rebase your code** and make sure that you are working on top of the most - recent version of the trunk branch, in case something has changed while you - were working on your code. +```sh +meson setup build +ninja -C build +ninja -C build install +``` -- **Update the locales** if you changed strings. The ninja target that you are - looking for is called `cartero-update-po` (such as `ninja -C build -cartero-update-po`). Don't worry, you don't have to translate the strings by - yourself, but make sure that the new templates are added to the .po and .pot - files. +To avoid installing system-wide the application, you can use a prefix: -- **Use the pre-commit hook**. The pre-commit hook will validate that your code - is formatted. It should be automatically configured if you run Meson in - development mode (`-Dprofile=development`), but you can install it on your - own or run `hooks/pre-commit.hook`. +```sh +meson setup build --prefix=/usr +ninja -C build +ninja -C build install +``` -The project is starting small, so if you want to do something big, it is best -to first start a discussion thread with your proposal in order to see how to -make it fit inside the application. +## Hacking and contributing -While this application is not official and at the moment is not affiliated with -GNOME, you are expected to follow the [GNOME Code of Conduct][coc] when -interacting with this repository. +**If you plan on contributing to the project**, use the development profile. +It will also configure a Git hook so that the source code is checked prior to +authoring a Git commit. The hook runs `cargo fmt` to assert that the code is +formatted. Read `hooks/pre-commit.hook` to inspect what the script does. -### Contributing with translations +```sh +meson setup build -Dprofile=development +``` -Do you want to use Cartero in your language? We are using [Weblate][weblate] -to coordinate and translate comfortably this project using a web interface. -Make an account and start proposing strings and they will be added to the -application. That will also entitle you as a contributor! +If you want to hack the source code and make your own changes to Cartero, you +can do it as long as you know enough Rust and enough about GTK and the rest of the +libraries it uses. Check out the [HACKING.md](HACKING.md) file. It provides instructions +useful for those who want to compile, test and run the application, specifically how to +compile the resource bundles and run the application. -### Contributing with feedback +If you want to share your changes with the world, you could send a pull request to +add the code to Cartero so that anyone can benefit from it. Information on how to +contribute has moved to [CONTRIBUTING.md](CONTRIBUTING.md). -Cartero is still getting new features, and hopes to be as useful as it can be. -Found a bug or something is wrong? Report it. An use case you are missing? -Report it. Show us how you integrate Cartero on your workflow so that we can -build our diverse list of use cases. +**Other ways to contribute to Cartero also include reporting bugs, sending feedback, +talking about Cartero to other people to make the project more popular, and sending +translations**. We are using [Weblate][weblate] to coordinate and translate comfortably +this project using a web interface. Make an account and start proposing strings and they +will be added to the application. That will also entitle you as a contributor! ## Licenses Cartero is published under the terms of the GNU General Public License v3.0 or later. ``` -Copyright 2024 the Cartero authors +Copyright 2024-2025 the Cartero authors This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -274,30 +209,18 @@ Attribution-ShareAlike 4.0 International license][ccbysa]. ## Credits and acknowledgments -Cartero is maintained by [Dani Rodríguez][danirod]. +Cartero is maintained by Dani Rodríguez. Big shoutout to the [contributors][contrib] who have sent patches or -translations! - -Also, Christian suggested Cartero as the name for the application and I liked -it enough to call it like so, therefore shoutout to Christian as well! - -Finally, shoutout to many of the GTK and GNOME Circle applications out there whose -source code I've read in order to know how to use some of the GTK features that -you cannot learn just by reading the official docs. - -## Blog - -Dani's [dev blog][blog] (in Spanish) of Cartero. +translations! Also, Christian suggested Cartero as the name for the +application and I liked it enough to call it like so, therefore shoutout +to Christian as well! [ccbysa]: https://creativecommons.org/licenses/by-sa/4.0/ -[coc]: https://conduct.gnome.org [contrib]: https://github.com/danirod/cartero/graphs/contributors -[danirod]: https://github.com/danirod -[fork]: https://github.com/danirod/cartero/fork -[blog]: https://danirod.es/secciones/devlogs/cartero/ [weblate]: https://hosted.weblate.org/projects/cartero/ [windows-x86_64]: https://github.com/danirod/cartero/releases/download/v0.1.4/Cartero-0.1.4-windows-x64.exe +[windows-portable-x86_64]: https://github.com/danirod/cartero/releases/download/v0.1.4/Cartero-0.1.4-windows-x64.zip [macos-sillicon]: https://github.com/danirod/cartero/releases/download/v0.1.4/Cartero-0.1.4-macOS-arm64.dmg [macos-intel]: https://github.com/danirod/cartero/releases/download/v0.1.4/Cartero-0.1.4-macOS-x64.dmg [appimage-x86_64]: https://github.com/danirod/cartero/releases/download/v0.1.4/Cartero-0.1.4-x86_64.AppImage diff --git a/doc/website/appimage.png b/doc/website/appimage.png index 7adcbe9..42ac36a 100644 Binary files a/doc/website/appimage.png and b/doc/website/appimage.png differ diff --git a/doc/website/bluesky.png b/doc/website/bluesky.png new file mode 100644 index 0000000..13b35c5 Binary files /dev/null and b/doc/website/bluesky.png differ diff --git a/doc/website/index.html b/doc/website/index.html index 0bff064..322f9d1 100644 --- a/doc/website/index.html +++ b/doc/website/index.html @@ -32,41 +32,55 @@

Get it on Flathub

-

Also available in Arch Linux AUR - and as a Nix flake.

-

Cartero is free software released as GNU GPL 3.0 or later. - The source code is available here.

+

Also available in other package managers.

+

Available as a Nix flake + and through Homebrew for macOS.

-

Also available as:

+

Download for your OS:

- +
+

Cartero is free software released as GNU GPL 3.0 or later. + The source code is available here.

+

For development updates, you can follow Cartero on Mastodon and other social networks of the fediverse (also bridging to Bluesky).

+
+
@@ -89,7 +103,7 @@

Test your APIs in a cozy environment