From e2bcb3416ab146a9eb50f6836f7c419b8ac5fb2b Mon Sep 17 00:00:00 2001 From: Shivram Date: Fri, 26 Sep 2025 12:43:32 +0530 Subject: [PATCH] addede a new readme file --- README.md | 177 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 106 insertions(+), 71 deletions(-) diff --git a/README.md b/README.md index aa08b8d..6df5fcd 100644 --- a/README.md +++ b/README.md @@ -1,104 +1,139 @@ -# archpkg-helper +# ๐Ÿš€ archpkg-helper -A command-line utility for simplifying package management on Linux distributions. This project aims to make installing, removing, and searching for packages easier, and welcomes contributions from the open source community. +A cross-distro command-line utility that helps you search for packages and generate install commands for native package managers (pacman, AUR, apt, dnf, flatpak, snap). It aims to make discovering and installing software on Linux simpler, regardless of your distribution. -## Table of Contents +## ๐Ÿ“‘ Table of Contents -- [About](#about) -- [Features](#features) -- [Installation](#installation) -- [Usage](#usage) -- [File Structure](#file-structure) -- [Contributing](#contributing) -- [License](#license) +- [๐ŸŽฏ About](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#about) +- [โœจ Features](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#features) +- [โšกQuick Start (install.sh)](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#quick-start-installsh) +- [๐Ÿ“ฆ Installation (Recommended: pipx)](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#installation-recommended-pipx) +- [๐Ÿ”ง Alternative Installation (pip)](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#alternative-installation-pip) +- [๐ŸŽฎ Usage](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#usage) +- [๐Ÿ“ File Structure](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#file-structure) +- [๐Ÿค Contributing](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#contributing) +- [๐Ÿ“„ License](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#license) -## About +## ๐ŸŽฏ About -archpkg-helper is designed for users who want an easier way to manage packages on Linux systems. While originally inspired by Arch Linux, this tool aims to work on any Linux distribution that supports Python and common package managers. Whether youโ€™re new to Linux or a seasoned user, this tool offers simple commands for common package operations. +archpkg-helper is designed to work across Linux distributions. While originally inspired by Arch Linux, it detects your system and generates appropriate install commands for common package managers. It's suitable for both newcomers and experienced users who want a simpler way to search and install packages. -## Features +## โœจ Features -- Install, remove, and search for packages with simple commands -- Support for dependencies and AUR packages (coming soon) -- Easy-to-read output and error messages -- Not bound to Arch Linuxโ€”can be used on other Linux distros with compatible package managers +Search for packages and generate install commands for: +- pacman (Arch), AUR, apt (Debian/Ubuntu), dnf (Fedora), flatpak, snap +- Cross-distro support (not limited to Arch) +- Clear, readable output and errors +- One-command setup via install.sh -## Installation +โšกQuick Start (install.sh) +Install directly using the provided installer script. -You can install archpkg-helper on any Linux distro. Here are the steps: +From a cloned repository: -### Prerequisites +git clone https://github.com/AdmGenSameer/archpkg-helper.git +cd archpkg-helper +bash install.sh +๐ŸŒ Or run directly from the web: + +curl -fsSL https://raw.githubusercontent.com/AdmGenSameer/archpkg-helper/main/install.sh | bash +# or +wget -qO- https://raw.githubusercontent.com/AdmGenSameer/archpkg-helper/main/install.sh | bash +โš ๏ธNotes: + +The installer ensures Python, pip, and pipx are available and installs the CLI via pipx. +You may be prompted for sudo to install prerequisites on your distro. +๐Ÿ“ฆ Installation (Recommended: pipx) +On Arch and many other distros, system Python may be โ€œexternally managedโ€ (PEP 668), which prevents global pip installs. pipx installs Python CLIs into isolated environments and puts their executables on your PATHโ€”this is the easiest, safest method. + +Install pipx +Arch Linux: +sudo pacman -S pipx +pipx ensurepath +Debian/Ubuntu: +sudo apt update +sudo apt install pipx +pipx ensurepath +Fedora: +sudo dnf install pipx +pipx ensurepath +Install archpkg-helper with pipx +Directly from GitHub: +pipx install git+https://github.com/AdmGenSameer/archpkg-helper.git +From a local clone: +git clone https://github.com/AdmGenSameer/archpkg-helper.git +cd archpkg-helper +pipx install . +Upgrade later with: -- Python 3.6 or newer -- `git` installed +pipx upgrade archpkg-helper +Ensure your shell session has pipxโ€™s bin path in PATH (pipx prints instructions after pipx ensurepath, typically ~/.local/bin). -### Steps +๐Ÿ”งAlternative Installation (pip) +If you prefer pip, install in user scope to avoid system conflicts: -```sh +From a local clone: git clone https://github.com/AdmGenSameer/archpkg-helper.git cd archpkg-helper -pip install . -``` +python3 -m pip install --user . +Directly from GitHub: +python3 -m pip install --user git+https://github.com/AdmGenSameer/archpkg-helper.git +If your distro enforces PEP 668 protections for global installs, you may see errors. You can bypass with: -Or for development: +python3 -m pip install --break-system-packages . +However, using pipx is strongly recommended instead of breaking system protections. -```sh -pip install -e . -``` +๐ŸŽฎ Usage +After installation, the CLI is available as archpkg. -## Usage +Examples: -After installing, use the following commands: +# Search for a package across supported sources +archpkg search -```sh -archpkg-helper install -archpkg-helper remove -archpkg-helper search -``` +# Generate install command(s) for a package +archpkg install + +# Generate removal command(s) for a package +archpkg remove +Additional: + +archpkg --help +archpkg --version +Replace with the package you want to manage. -Replace `` with the package you want to manage. +## ๐Ÿ“File Structure -## File Structure +Top-level layout of this repository: ``` archpkg-helper/ -โ”‚ -โ”œโ”€โ”€ archpkg_helper/ # Main Python package -โ”‚ โ”œโ”€โ”€ __init__.py -โ”‚ โ”œโ”€โ”€ cli.py # Command-line interface implementation -โ”‚ โ”œโ”€โ”€ core.py # Core logic for package management -โ”‚ โ””โ”€โ”€ utils.py # Utility functions -โ”‚ -โ”œโ”€โ”€ tests/ # Unit tests -โ”‚ โ”œโ”€โ”€ test_cli.py -โ”‚ โ””โ”€โ”€ test_core.py -โ”‚ -โ”œโ”€โ”€ setup.py # Python packaging configuration -โ”œโ”€โ”€ LICENSE # Project license (Apache 2.0) -โ”œโ”€โ”€ README.md # This file -โ””โ”€โ”€ CONTRIBUTING.md # Contribution guidelines +โ”œโ”€โ”€ archpkg/ # Core Python package code (CLI and logic) +โ”œโ”€โ”€ install.sh # One-command installer script (uses pipx) +โ”œโ”€โ”€ pyproject.toml # Build/metadata configuration +โ”œโ”€โ”€ setup.py # Packaging configuration (entry points, deps) +โ”œโ”€โ”€ LICENSE # Project license (Apache 2.0) +โ”œโ”€โ”€ README.md # Project documentation (this file) +โ”œโ”€โ”€ build/ # Build artifacts (may appear after builds) +โ”œโ”€โ”€ __pycache__/ # Python bytecode cache (auto-generated) +โ”œโ”€โ”€ archpkg_helper.egg-info/ # Packaging metadata (auto-generated) +โ””โ”€โ”€ archpy.egg-info/ # Packaging metadata (auto-generated) ``` -## Contributing - -We welcome contributions! Please read our [`CONTRIBUTING.md`](./CONTRIBUTING.md) for guidelines. - -### How to Contribute - -1. Fork the repository. -2. Create a branch: `git checkout -b feature-branch` -3. Make your changes and commit: `git commit -m "Describe your changes"` -4. Push to your fork: `git push origin feature-branch` -5. Open a Pull Request. +๐Ÿ’กSome metadata/build directories are generated during packaging and may not be present in fresh clones. -#### Issues +## ๐Ÿค Contributing -Report bugs or request features [here](https://github.com/AdmGenSameer/archpkg-helper/issues). +Contributions are welcome! Please: -## License +- Fork the repository +- Create a feature branch: git checkout -b feature-branch +- Make your changes and commit: git commit -m "Describe your changes" +- Push to your fork: git push origin feature-branch +- Open a Pull Request -This project is licensed under the [Apache License 2.0](./LICENSE). +Report bugs or request features via the [issue tracker](https://github.com/AdmGenSameer/archpkg-helper/issues). ---- +## ๐Ÿ“„ License -*Happy hacking!* \ No newline at end of file +This project is licensed under the [Apache License 2.0](https://github.com/AdmGenSameer/archpkg-helper/blob/main/LICENSE). \ No newline at end of file