inxi :: core mission
Page Version: 1.0 Page Updated: 2020-11-21
If you would like to submit patches for inxi, read and understand these core requirements for inxi. Patches not following these rules will be ignored.
Just so it's clear, as these may not be obvious to all. inxi has some core requirements that will never be changed. Failure to meet any of the following requirements is always a critical show stopper bug. These requirements have determined many of the critical development decisions in inxi. For example, the Perl version to use (Perl 5.008), the selection of Perl 5 in the firsst place, how features are developedd, tested, and optimized, how fallback cases are handled, how legacy methods are maintained in cascade testing, and so on. It's really not not possible to understand why things are the way they are in inxi without understading the following:
First and foremost: don't EVER work on inxi in the master branch!!! The development branch is inxi-perl, and the develoopment version is pinxi. This came about during the rewrite to Perl, so that I could compare pinxi (the perl version) against inxi (the bash version) to make sure the Perl inxi was feature complete or better on launch. This was so useful that I decided to just keep pinxi as the development version and branch permanently. Further, pinxi does NOT get merged into inxi, it gets copied over to inxi then committed. The two are standalone programs, that is. pinxi can best be thought of as next inxi, or inxi unstable, or inxi rolling.
inxi git 'branches' are made to emulate svn branches, which are physical static directories, not git style. I much prefered the svn way of handling branches, and still do, so I made git emuulate that. No merging every occurs between these 'branches'!
If you submit patches to the master branch, it means you did NOT read the README, and that's not a great way to start any collaboration.
pinxi is always ahead of inxi, except the days right around next inxi release, but pinxi is also very dynamic, which basically means, really, you need to talk to me before doing anything substantial, I don't use git merge features, I don't use branches in the way you might be used to, and the real master version of inxi is actually my local dev pinxi, which gets committed now and then to github.
Debugger data should always come using pinxi, since it may have newer debuggers added to deal with newer issues.
inxi must run on really old systems, using Perl version, 5.008. 5.008 Perl was picked because it's the first 'modern' Perl that is basically feature complete, and very little is required to make the code run on all Perls since 5.008 in terms of awareness of certain features that can't be used. The determination on the which Perl version to use was basically which Perl Redhat shipped with in 2008, give or take. 5.008 was a very good break point I've found, it's quite easy to write all code to work on that, and newer Perls. Any failure of code to run on 5.008 Perl is a critical bug and will be corrected immediately.
A corollary of this is that all new Perl 5 variants, including Perl 7. must work as well. Initial tests on Perl 5.032 with 7 test modules show inxi works fine on Perl 7.
No modules that are not in standard core modules are used for standard features, that is, inxi will never require any Perl module that is not in all the core modules since 5.008. Note that Redhat split out some modules from core modules, and that is handled where relevant by internal tests for the module, but it should in general not impact much for regular users.
Modules are only used if that is the absolute only way to achieve the result in a meaningful way. Modules are almost never required, that is, you can see from the top load / use section that very few are required. A few modules for special features regular users won't use, like export to json or xml, are loaded after the fact, and tested for, etc, if that feature is requested. But even there, the most basic module is used that will achieve the functionality.
Use of programs in subshells, like lm-sensors, lsblk, smartclt, hddtemp, etc, are always handled by testing for the tool, then showing appropriate alert messages if it's missing, or if it requires root to run.
As a subset of this rule, that means that it's actually fine to have new features that use tools that old operating systems didn't have, or that different platforms like BSDs, don't have, as long as the tools are tested for, handled, and error output where appropriate, is put in place if the feature can't work without the tool.
inxi always is installable, and upgradeable, as a single file, plus the man page once -U is used as root. This will never change, it's impossible to develop inxi without that core feature. This makes code-folding your friend!! While certain libraries might be added in the future for features that do not exist today, they would never be required to actually run inxi, for example, language support for non english. This feature appears increasingly unlikely to ever happen however.
Since the codebase and logic for inxi are quite old,and handle legacy situations as well as modern ones, in general, old methods are preserved, and a cascade of tests are used to determine which method to use. In other words, something that was required to get data in 2008 remains in place, and newer methods are simply integrated into the flow, via testing. This way the old stuff keeps working as expected, and new methods and solutions are used when available.
In keeping with requirement 1 is a further requirement that code that can be optimized in terms of execution speed should be optimized. If any technique or method can be demonstrated clearly to be faster than something else that produces the same reesult, that faster technique should be used. Now and then I revisit certain features that have expanded and expanded over time and test them, and have more than once sped up the feature by 100s of times, literally, by simply refactoring it. Differences that are only a few percent are unlikely to worth the time because they won't result in much improvement and could be CPU / system dependent, but loop tests of methods and syntaxes generally reveal real optimizations readily. Devel::NYTProf Perl optimizer is used now and then to catch glaring bottlenecks.
A last part of this is that once you run Devel::NTYProf you quickly realize that loading modules and running subshells is at least 90% of the execution time of inxi, so in particular, anything that can get rid of a subshell command and give the same or better results is good. That's particularly relevant with RAM files like /proc/ or /sys, which are super fast to read.
Once all this is clear, go back, and run inxi on a 100 mghz machine with a few 100 MB ram, and you'll quickly see why these things matter. inxi is actually tested on an ancient 200mghz mmx laptop now and then, just to keep it honest, and runs quite well on it, relatively speaking.
In terms of the actual code, just a few things: tabs, not spaces. Really. Readable code is preferred over terse code, unless the terse Perl is faster than the expanded, which happens. Note that I got better at Perl as I worked on Perl inxi, so there are certain ways of doing things I used at first during the rewrite to Perl I don't tend to use now. Those get updated as time goes along, but it's not a priority since it's time consuming. Other than that, just look at how things are done and that should be enough.
I consider inxi to be quite complicated, and some features are extremely interconnected, so really, make sure you understand why something is the way it is before assuming it was done wrong. Not everything is perfectly commented, but I do try to make unclear logics clear via comments where I notice that issue, but of course, sometimes something is clear when it's created...
I think that's it for the actual true core requirements of inxi/pinxi. Some of these might not be obvious as core requirements when all you've seen is distro packaged inxis, but once you start running inxi on very old hardware and operating systems, the reason for the requirement grows very obvious very quickly.