Skip to content

API changelog

Jump to bottom Edit New page
Eric Pailleau edited this page Oct 25, 2020 · 53 revisions

[WIP] Release >= 2.8 dev branch

"Absurd" results, due to some code testing function presence for example, will be discarded from result, a log warning raised and "?" set in output for Min and Max for related module.

rebar3 profiles handling.

Release >= 2.7

Major rewrite and new geas_db database format including semver string of (possibly non continue) versions of exported MFAs. Now a default T tag is shown with semver compatibility of project unless a GEAS_MY_RELS variable is set.

Release >= 2.6

New environment variables :

  • GEAS_FRAME : string. Set a semver range for release frame check.
  • GEAS_UPDATE : boolean. Ask to update otp_versions.table from erlang repository on github.
  • GEAS_HTTP_OPTS : string. Erlang term as string for httpc client options (proxy, etc...)

GEAS_FRAME is a semver range to be included in the release window computed. It is someway the opposite of GEAS_RANGE, and probably what most users expected for version control. BTW, both range and frame can be used at same time, but both must succeed for an exit 0.

Patch analyze is using otp_versions.table in geas private directory. Unfortunately this was requiring to release a Geas version at all new erlang patch published by OTP team. Using GEAS_UPDATE=1 will download the last current version of this file locally. GEAS_HTTP_OPTS will allow to pass (proxy ?) options to httpc:set_options/1 under an Erlang term as a string, with a final dot like in config files.

Environment variables GEAS_* can now be set in rebar.config in minuscule atoms, without geas_ prefix, for plugin. For exemple : GEAS_RANGE=">=19.2 || < 21.3" can be written as {geas, [{range, ">=19.2 || <21.3"}]}.

geas is now aware of caller, rebar3 or erlang.mk, and select right beam files, even if both tools are used locally, with directories _build/, deps/ and ebin/ present at same time.

Release >= 2.5

Geas, modules and project versions are now displayed on right side of output (limited to 20 chars).

Patches list (P) is now sorted lower to higher versions, like recommended patch list (R).

geas:what/1 is returning a new tuple with maximum opcode declared in Beam file:

   {max_opcode, Integer}, % Max opcode declared in Beam file

Environment variable GEAS_RANGE allow to set a required range of version for the project. Goal is to let use geas plugin in your CI process by exiting non zero on error.

POTENTIAL INCOMPATIBILITY

erlang.mk plugin now exit 2 on error. GNU make is always exiting 2 on error, but below error codes are written in logs in case of error.

Rebar plugin is now exiting below code as exit code in case of error.

Error codes are :

  • 1 if current version is incompatible with release window.
  • 2 if release window do not match a required semver version range set with GEAS_RANGE.
  • 3 if Beam file is incompatible with current Erlang/OTP release (missing chunk). (May work by recompiling source)
  • 4 if maximum opcode is higher in Beam file than current Erlang/OTP release. (May work by recompiling source)

Release >= 2.2

As CORBA module(s) was moved from core Erlang, those modules are now marked as removed in Geas database. This may change in future.

Release >= 2.1

Information displayed depending environment variables are slightly changed. A single capital letter is now used as tag.

  • T = Total (All releases inside computed window)
  • L = Local (All local releases given by GEAS_MY_RELS inside computed window)
  • D = Discarded (Discarded releases)
  • E = Excluded (Excluded release)
  • C = Current (Current Erlang major.minor release used, for example 20.2)
  • P = Patches (Patches detected to be installed on current release, for example 20.2.2)

New tag shown when using GEAS_TIPS=1

  • R = Recommended (Patches that should be applied, because code is using module impacted by a patch for current version)

A new process dictionary entry is now available after compat run :

  • geas_apps : lists of Erlang applications detected

Logs are now printed on standard error output, and can then be redirected in a file if necessary.

Release >= 2.0.12

BEAM format starting 20.0 add new chunk types "AtU8" and "Dbgi". Geas handle this correctly.

Release >= 2.0.8

Compilation datetime is not anymore in beam file starting 19.0. API functions return {datetime, undefined} in such case.

Release >= 2.0.6

Now by default, some releases can be discarded from release window when some module/function/arity used. For now only R16B03 + syntax_tools is discarded. All known issues is to be declared in src/geas_disc.hrl. To disable this feature, simply export GEAS_DISC_RELS=0 environment variable.

GEAS_LOG environment variable let you tune geas logging. If set, allow logging. If set empty, all log levels are printed. Set with a blank separated list of loglevels, print only those ones. Allowed loglevels are : debug, notice, warning, error.

Some process dictionary entries are now available after compat run :

  • geas_calls : list of distinct MFA tuples of all calls in code .
  • geas_logs : list of all geas logs, in tuple format {LogLevelAtom, ReasonTerm, FileString}
  • geas_disc : list of discarded releases, in tuple format {FileString, [{{M, F, A}, {DiscardRelList, OTPBugFixAtom}} |...] }
  • geas_minrels : list of {MinRelNameString, {M, F, A}}. MinRelNameString = undefined for non Erlang MFAs.
  • geas_maxrels : list of {MaxRelNameString, {M, F, A}}. MaxRelNameString = undefined for non Erlang MFAs.

Release >= 2.0.5

Function w2l/1 return the official Erlang release list from a usual compat release window tuple. The returned list take into account both environment variables GEAS_MY_RELS and GEAS_EXC_RELS if set. Those variables are respectively a list of local release available and a list of excluded releases. Format is a blank separated list of official Erlang release names.

Release >= 2.0.4

Function compat/2 is added. First argument is root directory of a project, second an atom :

  • print : Same as compat/1. Print global compatibility and dependancies details, like plugins does.
  • global : Compatibility of code with official releases including dependancies, returned as usual compat tuple term {MinDbRel, MinRel, MaxRel, MaxDbRel}.
  • deps : List of dependancies compatibility tuples.

Environment variable GEAS_USE_SRC set to "1" tell Geas to use source file instead of beam files. If unset or set to "0", Geas use source file as fallback, if available, to extract abstract code if unavailable in beam file.

Release >= 2.0

A new major feature is added to already existing exported functions: compat entry, which gives you the official Erlang release window where the beam file(s) can run on. For example : using application:ensure_all_started/1 can only be used starting R16B01 or maps starting 17.0. As well pg module cannot be used after 17.5. This can help you to :

  • Write your Travis CI (or equivalent) config file
  • Know if beam files can run with an Erlang VM
  • Verify that your dependencies can run on same Erlang release window than your project
  • Write clear statements in your README project files
  • Modify your code in order to increase runnable release window
  • Know if application/module have to be fixed in order to run on the last official release

A new function is exported : geas:offending/1 which tells you what are the offending functions that reduce the runnable VM versions. Works only on a single beam file, i.e argument is the path to this file. Return {ok, {MinOffendingList, MaxOffendingList}} .

Release 1.1.0

Another function is added : geas:what/1

Argument is expected to be either a directory containing .beam files or a path to a single .beam file.

Output is almost the same than geas:info/1 but several tuple entries are removed instead of setting to undefined.

The purpose of this function is mainly to be used on .beam files in production environment.

Release 1.0.0

Only one function is exported : geas:info/1 .

Argument is expected to be a root project directory, and geas will look into ebin/ and use vcs informations if available. Directories ebin and src must exist.

geas:info/1 won't work on a simple directory containing .beam files. geas:info/1 won't work by passing a path to a .beam file.

Informations may be set to undefined atom, in some cases, for example if no vcs infos are found.

Add a custom footer
Add a custom sidebar
Clone this wiki locally