Engee documentation

Working with EngeePkg

Use the EngeePkg package to clearly separate user and system packages and to provide advanced functionality for working with them in your project.

EngeePkg is an add—on to the Pkg package manager, implemented as a standalone package for better control over downloaded modules and packages.

EngeePkg has the following advantages over Pkg:

  • EngeePkg distinguishes between system and user packages, distinguishing among the system packages those that are included in the system image. By default, the EngeePkg.status function outputs all information from LOAD_PATH. Classic Pkg with the Pkg.status function It does not have such functionality and provides information about packages from only one project (active by default). Moreover, 'EngeePkg.status', unlike `Pkg.status', can provide information about loaded modules.

  • EngeePkg cleans up the entire user project by removing all installed packages with the EngeePkg.purge function without explicitly listing. Classic Pkg cleans up the project with the Pkg.rm function, but requires explicit enumeration of all packages.

To work with EngeePkg, add it to the current environment (project):

Pkg.add("EngeePkg")

Import EngeePkg into the workspace (command line or script editor):

using EngeePkg

Refer to the help on the command line (use a question mark ? to switch to the help' mode?) to output the available EngeePkg commands:

ALL_MODULES         CLI                 INIT_MODULES        INSTALLED_MODULES
LOADED_MODULES      PKGMODE_MANIFEST    PKGMODE_PROJECT     PKGSORT_BY_NAME
PKGSORT_BY_SRCPATH  PKGSORT_BY_UUID     PKGSORT_NONE        PkgUtils
SYSTEM_MODULES      Status              USER_MODULES        eval
include             purge               select_packages     status

Next, let’s look at the functions EngeePkg.status and EngeePkg.purge using specific examples.

The EngeePkg.status function

The EngeePkg.status function displays the status of installed packages and/or downloaded modules. Unlike Pkg.status, EngeePkg.status can provide information about downloaded modules, distinguish between system and user packages, and determine which ones are included in the system image.

Signature of the EngeePkg.status function:

EngeePkg.status(modules::Union{String, UUID, Module, ModuleSelection};
                  mode::PackageMode, sort::PkgSortOrder, outdated::Bool, io::IO)

The optional first argument `modules' specifies the selection of packages/modules. This can be the name or UUID of one specific package, or one module as such, or a constant specifying many packages/modules.:

  • 'USER_MODULES' — installed from user packages.

  • `SYSTEM_MODULES' — installed from system packages.

  • `INSTALLED_MODULES' — installed in all projects (lists packages from all LOAD_PATH elements).

  • `LOADED_MODULES' — loaded into memory (including not installed ones).

  • 'INIT_MODULES' — loaded into memory from the system image.

  • 'ALL_MODULES' (by default) — all installed and downloaded packages (lists packages from all LOAD_PATH elements).

The io argument specifies the terminal for output (by default stdout).

The sort argument sets the enumeration order:

  • `PKGSORT_BY_NAME' — sort by package names;

  • `PKGSORT_BY_SRCPATH' — sort by location of source files of installed packages;

  • `PKGSORT_BY_UUID' — sort by package UUID;

  • `PKGSORT_NONE' (by default) — without sorting.

The mode argument sets the selection mode for installed packages:

  • `PKGMODE_PROJECT' — by project file (Project.toml);

  • `PKGMODE_MANIFEST' — by the manifest file (Manifest.toml).

When selecting only installed packages ('USER_MODULES', SYSTEM_MODULES', `INSTALLED_MODULES), a file containing data on the direct dependencies of the project is used by default (Project.toml). When selecting uploaded files (LOADED_MODULES', `INIT_MODULES', `ALL_MODULES), as well as when selecting by name and UUID, a file describing the project data structure (Manifest.toml).

The output uses the same format as `Pkg.status'. When selecting packages from several projects, the icons ①, ②, etc. are used to distinguish them. The ▣ icon marks downloaded packages. For example:

Status ① `/user/.project/Manifest.toml`
             ② `/usr/local/julia-1.9.3/environments/v1.9/Manifest.toml`
 ⌅ [39de3d68] AxisArrays v0.4.6 ② ▣
 ⌅ [98e50ef6] JuliaFormatter v1.0.20 ② ▣
   [2aef5ad7] QueryOperators v0.9.3 ②
 ⌅ [48965c70] MatrixPencils v1.7.5 ② ▣
 ⌃ [69666777] Arrow v2.4.3 ②
   [49dc2e85] Calculus v0.5.1 ② ▣
   [efcefdf7] PCRE2_jll v10.42.0+0 ② ▣
 ⌅ [d8a4904e] MutableArithmetics v1.1.0 ② ▣
 ⌅ [aacddb02] JpegTurbo_jll v2.1.91+0 ② ▣

The Pkg.status function of the Pkg package manager can provide information about packages from only one project (active by default). For example:

Status `/user/.project/Project.toml`
  [e36ba207] EngeePkg v0.0.7
  [4d00f742] GeometryTypes v0.8.5
⌅ [23fbe1c1] Latexify v0.15.18

The EngeePkg.status function is joined by EngeePkg.select_packages'. If 'status prints information in human-readable form, then select_packages returns the same information as a data object that can be worked with programmatically.

Signature of the select_packages function:

EngeePkg.select_packages(modules::Union{String, UUID, Module, ModuleSelection},
                           mode::PackageMode)

The 'select_packages` function receives a selection of installed packages and/or downloaded modules as an array of package descriptions. The arguments modules and `mode' have the same meaning as in `EngeePkg.status'.

EngeePkg.purge function

The 'purge` function deletes all packages installed in the specified environment (by default, in the user’s project):

EngeePkg.purge()
The output of the command execution
Updating `/user/.project/Project.toml` # removing packages from Project.toml (custom)
  [c3fe647b] - AbstractAlgebra v0.27.8
  [7d9f7c33] - Accessors v0.1.27
  [79e6a3ab] - Adapt v3.5.0
  [e36ba207] - EngeePkg v0.0.7
  [cd3eb016] - HTTP v1.5.4
  ...
  [91a5bcdd] - Plots v1.36.1
  [c3e4b0f8] - Pluto v0.19.40
  [438e738f] - PyCall v1.94.1
  [d330b81b] - PyPlot v2.11.2
  [3646fa90] - ScikitLearn v0.7.0
  [6a2ea274] - Torch v0.1.0
    Updating `/user/.project/Manifest.toml` # #removing packages from Manifest.toml (system)
  [c3fe647b] - AbstractAlgebra v0.27.8
  [7d9f7c33] - Accessors v0.1.27
  [79e6a3ab] - Adapt v3.5.0
  [b99e7846] - BinaryProvider v0.5.10
  [d1d4a3ce] - BitFlags v0.1.7
  ...
  [d360d2e6] - ChainRulesCore v1.15.7
  [944b1d66] - CodecZlib v0.7.1
  [19ecbf4d] - Codecs v0.5.0
  [35d6a980] - ColorSchemes v3.20.0
  [3da002f7] - ColorTypes v0.11.4

The function is used to completely clean up the user’s project. The Pkg package manager does not support this functionality — the Pkg.rm function is available, for which only an explicit enumeration of all packages is available.