================================================================================ README for development repo of inxi: pinxi ================================================================================ FILE: README.txt VERSION: 5.19 DATE: 2024-01-14 NOTE: While the real program name will never change, for the sake of clarity, the development version of inxi is called pinxi, so it can be run next to either inxi-legacy (binxi) or master (inxi). See DOCS and TOOLS sections for developer information and backend tools. NOTE: This repo originally started as the inxi-perl branch in the inxi repo, but because pinxi has grown to be the actual development version, standalone, of inxi, it has been split off into its own repo. Please do not confuse this for the stable master branch in the inxi repo!! This is highly unstable, and can, and does, break when under heavy development, and is for users who want to be on the cutting edge of inxi development and don't mind occasioanal breakages. To keep things maintainable, issues go to inxi issues. -------------------------------------------------------------------------------- CODEBERG SOURCE REPO -------------------------------------------------------------------------------- Packagers: Make sure to change your package URLs and repos to use codeberg.org. inxi (main, master): REPO: https://codeberg.org/smxi/inxi BRANCH: master pinxi (development inxi): REPO: https://codeberg.org/smxi/pinxi BRANCH: master ISSUES: https://codeberg.org/smxi/inxi/issues The github based inxi-perl branch was rebuilt and now only contains the pinxi, pinxi.1 files, plus a minimal README.txt for github users. docs and tarballs have been deleted. The inxi-perl branch should not be used, and exists only so that current pinxi users can update from there to get a version with the new self updater URLs. inxi master will be mirrored until most distro packagers have changed to using codeberg, then it will no longer get updates. The github inxi/inxi-perl branch is no longer getting updates, and exists only to provide a pinxi with the codeberg update urls. The inxi repo only contains master, plus the one, two branches, which are obsolete but are internally supported by inxi -U 1 and -U 2. -------------------------------------------------------------------------------- Please take the time to read this helpful article from the Software Freedom Conservancy: https://sfconservancy.org/GiveUpGitHub/ Any use of this project's code by GitHub Copilot, past or present, is done without my permission. I do not consent to GitHub's use of this project's code in Copilot. ================================================================================ Clone pinxi: git clone https://codeberg.org/smxi/pinxi Install pinxi for testing. Note that the -U option works the same as the inxi main repo master branch, so only the initial install is required: wget -O pinxi https://codeberg.org/smxi/pinxi/raw/master/pinxi Shortcut download path for codeberg.org (easier to remember and type): wget -O pinxi smxi.org/pinxi pinxi -U --man also installs the man page from pinxi, which is the development branch for the master man page. ================================================================================ DONATE: Help support the project with a one time or a sustaining donation. Paypal: https://www.paypal.com/donate/?hosted_button_id=77DQVM6A4L5E2 LiberaPay (sustaining donations): https://liberapay.com/smxi/ ================================================================================ DOCS: The pinxi repo /docs contain the data needed to develop inxi/pinxi. See: docs/perl-programming.txt Tips and hints on how to translate other language logic to Perl, and Bash stuff in particular. Note, I will never be a Perl expert, nor do I want to be. I want the code to be 'newbie' friendly, and to be accessible to reasonably smart people who do not happen to be Perl experts, but do understand basic programming logic. Perl was selected because it is much easier to work with than the bash/gawk/sed/grep/etc mix that ran in binxi, and because the 5.x branch has proved itself to be very solid over years, without breaking stuff needlessly on updates. In a way, it was a blessing that Larry made Perl6, and now calls it a different language, because that removed the pressure from Perl 5 to break itself by trying to become Perl 6. See: docs/perl-setup.txt How to set up your Perl dev stuff See: docs/perl-version-support.txt Notes on what features can be used for the Perl version. 5.08 is the current cutoff. No newer features will be used, this lets inxi maintain its core mission of supporting almost everything, no matter how old. See: docs/inxi-*.txt Granular documentation files for inxi features. There's a lot, so dig in! See: docs/inxi-tools.txt Core tools available for features and modules. Since most log their data, it's always preferable using a core tool than to recode it again. With some exceptions, for example, extreme repetitions where you want to remove any possible overhead in the action. See: docs/inxi-values.txt User config options; the values of the primary hashes that contain the switches used for layout, option control, downloader, konvi etc. inxi-values.txt is the primary reference document for working on inxi/pinxi. ================================================================================ TOOLS: There are a few backend tools that are used to generate matching tables for various types of data. These are located in pinxi/tools/ and all have a -h / --help menu and significant and useful debugger output tools so you can see what is happening if something isn't working as hoped. Because these always require manual updates using empirical research and data, they are developed stand-alone to make it easier to update them, and also easier for other people to work on them, and, ideally, to contribute patches to improve matches. Well, I can dream, can't I? LOL. 1. tools/cpu_arch.pl - tool to update cp_cpu_arch. As with vendors.pl, this is the master copy of cp_cpu_arch, which you copy from cpu_arch.pl to replace cp_cpu_arch in pinxi. Includes debuggers to test cpu types, model, stepping, name strings. 2. tools/disk_vendors.pl - create new set_disk_vendors() sub for pinxi, use this to add new vendor and vendor product matches. Don't touch if you don't know regex quite well! Creates matching table for disk vendors: item. * tools/lists/: disks.[full|unhandled|vendors].txt - the various lists of disk data used, and generated. 3. tools/gpu_ids.pl - tool to generate amd/intel/nvidia microarch, and legacy driver ids for the inxi nvidia graphics architecture and non-free driver information. Creates raw matching IDs for gpu_data item, again matching hash tables. Copy and paste the changed id rows from terminal to corresponding gpu data function. * tools/lists/: gpu.[amd|intel|nv.[driver]].full.sort contain PCI IDs for arch matching. These are generated by gpu_raw.pl. 4. tools/gpu_raw.pl - generate AMD, Intel, Nvidia gpu id files from raw source data using some clever transformation tricks, makes all source data turn into the same output so gpu_ds.pl can read it easily. Creates gpu.[amd|intel|nv.[driver]].full.sort files for gpu_ids.pl. * tools/lists/: Source device ID files are gpu.[amd|intel|nv.[driver]].[manual|raw] and pci.ids.*. 5. tools/ram_vendors.pl - similar to vendors.pl only much more simple. Allows for testing of unhandled ram model strings in cases where id failed. Also includes the vendor id matching table, so you can also update that, though it's not used in this logic yet, but is in pinxi. Use to confirm new matching patterns before copying / pasting changed block into pinxi ram section. ================================================================================ DATA: The data/ directory contains the raw data used by --fake data feature. Only use if you are developing pinxi actively, they are very useful. It's quite difficult to work on some features of inxi without having ready access to sample data files from a wide range of systems, so now wherever possible new data files are released concurrently with the feature's development. Note that location of this directory in pinxi defaults to: $HOME/bin/scripts/inxi/data but you can change it to be wherever you want with the global configuration item: FAKE_DATA_DIR=[full path to data dir, do not end with slash] You can test this path with --fake-data-dir [path]. Use /etc/pinxi.conf to set path so that it's global. Some of the data is more general data, not meant to be inserted as fake data, but most is fake data to emulate various systems and features. ================================================================================ BASIC IDEA: I was sufficiently impressed switching from xiin python script to creating two small Perl functions to do the primary /sys debugging actions that Perl for inxi struck me as an increasingly interesting idea. Plus, Perl was so comically, absurdly, fast, that I could not ignore it. Another big reason this is being given real thought is that while an absolutely core, primary, requirement, for inxi, is that it run anywhere, on any nix system, no matter how old (practially speaking, 10 years old or newer), that is, you can pop inxi on an old server and it will work. Bash + Gawk will always, and has always, met that requirement, but that combination, with the lack of any real way to pass data, create complex data structures, etc., has always been a huge headache to work with. However, unlike in 2007, when the basic logic of inxi was started, and Perl 6 was looming as a full replacement for Perl 5, in 2017, Perl 5 is now a standalone project, and seems to have a bright future, and given that 5.08 is now old enough to satisfy the basic run anywhere on anything option, that would be the basic Perl version that would be used and tested against. I've vacillated a bit between 5.10 and 5.8, but after more research, I've realized there will always be old Redhat servers etc out there that are running Perl 5.8, and there is not a huge gain to using 5.10 from what I can see. pinxi/inxi has been tested on systems that run 5.08, 5.10, 5.12, and of course, modern Perl latest version. So yes, there are plenty of old servers and systems out there still running Perl 5.08. ================================================================================ ROADMAP: pinxi now running as the development version of inxi, with its own repo. As such, it will be either the same as, or ahead of, briefly, inxi, until the two are synced, where it starts over. There is only one feature remaining from the original roadmap that is left as a to-do: 1. Adding support for language hashes, that would replace the hack key values in the print arrays with the alternate language equivalent. Or, if missing that key, print the english. That would solve the issue of people flaking out on language support over time. Status: NOT Started (but support is designed in as I go along) This will only be added if there is real support and interest, there is an active issue on the master branch inxi about this, so if someone steps forwards and wants to do contribute, then it will happen, and if nobody does, then it will not happen. ================================================================================ BSD Development: Please note, after really struggling with BSD development, I have concluded that I will only do it under these circumstances: 1. a fully tested robust patch that does not break any existing logic is given. 2. I am given direct SSH access to the machine, or a machine/OS very much like it. VMs do not cut it for most advanced hardware stuff, but are OK for basic development work. Anything else is simply too time consuming for me to justify at this point. Note that I have access to some BSD machines, and those reflect accurately where the support can go if I have access. This means ok, but not totally complete, which is the best I can really hope for given the diverse state of the BSD OS ecosystem, which is simply too splintered to really support at random (didn't anyone ever hear the warning fable about sticks in a bundle being harder to break than a thick stick alone?). But with machine access my experience has shown me that I can make quite good progress on most BSDs, at least those that have available data, which is not always a given.