================================================================================
README for development repo of inxi: pinxi
================================================================================
FILE:    README.txt
VERSION: 5.20
DATE:    2024-03-28

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 
legacy inxi (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 github 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

Github smxi/inxi repos and branches stopped getting updated December, 2023. They
are now by definition obsolete.

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, that is, you can pop inxi on an 
old server and it will work as long as the system has Perl 5.008 or newer. 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., had always been a huge headache to work with, and I never want to deal 
with it again.

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. Since it has never happened, I no longer expect this to happen 
in the future. 

================================================================================

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, particularly if it's a generic feature in a default vm image 
causing the problems.

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 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.