README
Readme.md
1libcpuid
2========
3
4libcpuid provides CPU identification for the x86 (and x86_64).
5For details about the programming API, you might want to
6take a look at the project's website on sourceforge
7(http://libcpuid.sourceforge.net/). There you'd find a short
8[tutorial](http://libcpuid.sf.net/documentation.html), as well
9as the full [API reference](http://libcpuid.sf.net/doxy).
10
11Configuring after checkout
12--------------------------
13
14Under Linux, where you download the sources, there's no
15configure script to run. This is because it isn't a good practice to keep
16such scripts in a source control system. To create it, you need to run the
17following commands once, after you checkout the libcpuid sources
18from github:
19
20 1. run "libtoolize"
21 2. run "autoreconf --install"
22
23You need to have `autoconf`, `automake` and `libtool` installed.
24
25After that you can run `./configure` and `make` - this will build
26the library.
27
28`make dist` will create a tarball (with "configure" inside) with the
29sources.
30
31Prerequisites
32-------------
33
34Using libcpuid requires no dependencies on any of the supported OSes.
35Building it requires the aforementioned libtool and autotools commands
36to be available, which is a matter of installing a few common packages
37with related names (e.g. automake, autoconf, libtool).
38It also requires a POSIX-compatible shell. On NetBSD, you may need
39to install one (credits to @brucelilly):
40
411. Install a POSIX-compatible shell such as ksh93
42 (pkg_add ast-ksh || pkgin in ast-ksh)
432. export CONFIG_SHELL=/usr/pkg/bin/ksh93 (substitute the
44 correct path if required)
453. Follow the regular Linux instructions
46
47Testing
48-------
49
50After any change to the detection routines or match tables, it's always
51a good idea to run `make test`. If some test fails, and you're confident
52that the test is wrong and needs fixing, run `make fix-tests`.
53
54You can also add a new test (which is basically a file containing
55the raw CPUID data and the expected decoded items) by using
56`tests/create_test.py`. The workflow there is as follows:
57
581. Run "cpuid_tool" with no arguments. It will tell you that it
59 has written a pair of files, raw.txt and report.txt. Ensure
60 that report.txt contains meaningful data.
612. Run "tests/create_test.py raw.txt report.txt > «my-cpu».test"
623. Use a proper descriptive name for the test (look into tests/amd
63 and tests/intel to get an idea) and copy your test file to an
64 appropriate place within the tests directory hierarchy.
65
66For non-developers, who still want to contribute tests for the project,
67use [this page](http://libcpuid.sourceforge.net/bugreport.php) to report
68misdetections or new CPUs that libcpuid doesn't handle well yet.
69
70Users
71-----
72
73So far, I'm aware of the following projects which utilize libcpuid (listed alphabetically):
74
75* CPU-X (https://github.com/X0rg/CPU-X)
76* fre:ac (https://www.freac.org/)
77* I-Nex (https://github.com/i-nex/I-Nex)
78* Multiprecision Computing Toolbox for MATLAB (https://www.advanpix.com/)
79* ucbench (http://anrieff.net/ucbench)
80
81We'd love to hear from you if you are also using libcpuid and want your project listed above.
82
83Downloads
84---------
85
86You can find latest versioned archives [here](https://github.com/anrieff/libcpuid/releases/latest), with binaries for macOS and Windows.
87
88#### Binary packages
89
90Also, libcpuid is available for following systems in official repositories:
91
92* [Debian (since version 11 "Bullseye")](https://packages.debian.org/source/bullseye/libcpuid): `apt install cpuidtool libcpuid14 libcpuid-dev`
93* [Fedora (since version 25)](https://src.fedoraproject.org/rpms/libcpuid): `dnf install libcpuid libcpuid-devel`
94* [FreeBSD (since version 11)](https://www.freshports.org/sysutils/libcpuid): `pkg install libcpuid`
95* [OpenMandriva Lx (since version 4.0 "Nitrogen")](https://github.com/OpenMandrivaAssociation/libcpuid): `dnf install libcpuid-tools libcpuid14 libcpuid-devel`
96* [openSUSE Leap (since version 15.1)](https://software.opensuse.org/package/libcpuid): `zypper install libcpuid-tools libcpuid14 libcpuid-devel`
97* [Solus](https://packages.getsol.us/shannon/libc/libcpuid/): `eopkg install libcpuid libcpuid-devel`
98* [Ubuntu (since version 20.04 "Focal Fossa")](https://packages.ubuntu.com/source/focal/libcpuid) : `apt install cpuidtool libcpuid14 libcpuid-dev`
99
100#### Build tool
101
102* Vcpkg: `vcpkg install cpuid`
103