Upgrading

JLSO.jl will automatically upgrade older versions of the file format when you call JLSO.load or read.

using JLSO
dir = joinpath(dirname(dirname(pathof(JLSO))), "test", "specimens")
jlso = read(joinpath(dir, "v1_bson.jlso"), JLSOFile)

JLSOFile([ZonedDateTime, DataFrame, Vector, DateTime, String, Matrix, Distribution]; version="3.0.0", julia="1.1.0", format=:bson, compression=:none, image="")

Upgrading to v3 requires generating a new manifest and project fields from the legacy pkgs field (as seen above) which can be slow and may require manual intervention to address package name collisions across registries. JLSO.upgrade can be used to mitigate these issues.

To upgrade a single file:

JLSO.upgrade(joinpath(dir, "v1_bson.jlso"), "v3_bson.jlso")

 Activating new environment at `/tmp/jl_qqan4s/Project.toml`
  Resolving package versions...
Updating `/tmp/jl_qqan4s/Project.toml`
  [39de3d68] + AxisArrays v0.3.0
  [fbb218c0] + BSON v0.2.3
  [b99e7846] + BinaryProvider v0.5.4
  [34da2185] + Compat v2.1.0
  [a93c6f00] + DataFrames v0.18.2
  [31c24e10] + Distributions v0.20.0
  [8f5d6c58] + EzXML v0.9.1
  [9da8a3cd] + JLSO v1.0.0
  [f28f55f0] + Memento v0.12.1
  [78c3b35d] + Mocking v0.5.7
  [f269a46b] + TimeZones v0.9.1
Updating `/tmp/jl_qqan4s/Manifest.toml`
  [7d9fca2a] + Arpack v0.4.0
  [68821587] + Arpack_jll v3.5.0+3
  [56f22d72] + Artifacts v1.3.0
  [39de3d68] + AxisArrays v0.3.0
  [fbb218c0] + BSON v0.2.3
  [9e28174c] + BinDeps v0.8.10
  [b99e7846] + BinaryProvider v0.5.4
  [324d7699] + CategoricalArrays v0.7.7
  [34da2185] + Compat v2.1.0
  [e66e0078] + CompilerSupportLibraries_jll v0.3.4+0
  [9a962f9c] + DataAPI v1.10.0
  [a93c6f00] + DataFrames v0.18.2
  [864edb3b] + DataStructures v0.17.20
  [e2d170a0] + DataValueInterfaces v1.0.0
  [31c24e10] + Distributions v0.20.0
  [8f5d6c58] + EzXML v0.9.1
  [8197267c] + IntervalSets v0.3.2
  [c8e1da08] + IterTools v1.4.0
  [82899510] + IteratorInterfaceExtensions v1.0.0
  [692b3bcd] + JLLWrappers v1.4.1
  [9da8a3cd] + JLSO v1.0.0
  [682c06a0] + JSON v0.21.3
  [f28f55f0] + Memento v0.12.1
  [e1d29d7a] + Missings v0.4.5
  [78c3b35d] + Mocking v0.5.7
  [4536629a] + OpenBLAS_jll v0.3.9+5
  [bac558e1] + OrderedCollections v1.4.1
  [90014a1f] + PDMats v0.9.12
  [69de0a69] + Parsers v2.3.1
  [2dfb63ee] + PooledArrays v0.5.3
  [21216c6a] + Preferences v1.3.0
  [1fd47b50] + QuadGK v2.4.2
  [b3c3ace0] + RangeArrays v0.3.2
  [189a3867] + Reexport v0.2.0
  [79098fc4] + Rmath v0.5.1
  [a2af1166] + SortingAlgorithms v0.3.1
  [276daf66] + SpecialFunctions v0.7.2
  [2913bbd2] + StatsBase v0.30.0
  [4c63d2b9] + StatsFuns v0.8.0
  [cea106d9] + Syslogs v0.3.0
  [fa267f1f] + TOML v1.0.3
  [3783bdb8] + TableTraits v1.0.1
  [bd369af6] + Tables v0.2.11
  [f269a46b] + TimeZones v0.9.1
  [30578b45] + URIParser v0.4.1
  [2a0f44e3] + Base64
  [ade2ca70] + Dates
  [8bb1440f] + DelimitedFiles
  [8ba89e20] + Distributed
  [9fa8497b] + Future
  [b77e0a4c] + InteractiveUtils
  [76f85450] + LibGit2
  [8f399da3] + Libdl
  [37e2e46d] + LinearAlgebra
  [56ddb016] + Logging
  [d6f4376e] + Markdown
  [a63ad114] + Mmap
  [44cfe95a] + Pkg
  [de0858da] + Printf
  [9abbd945] + Profile
  [3fa0cd96] + REPL
  [9a3f8284] + Random
  [ea8e919c] + SHA
  [9e88b42a] + Serialization
  [1a1011a3] + SharedArrays
  [6462fe0b] + Sockets
  [2f01184e] + SparseArrays
  [10745b16] + Statistics
  [4607b0f0] + SuiteSparse
  [8dfed614] + Test
  [cf7118a7] + UUIDs
  [4ec0a83e] + Unicode
 Activating environment at `~/work/JLSO.jl/JLSO.jl/docs/Project.toml`

To batch upgrade files created with the same environment:

filenames = ["v1_bson.jlso", "v1_serialize.jlso"]
JLSO.upgrade(joinpath.(dir, filenames), filenames)

 Activating new environment at `/tmp/jl_YCfgGu/Project.toml`
  Resolving package versions...
Updating `/tmp/jl_YCfgGu/Project.toml`
  [39de3d68] + AxisArrays v0.3.0
  [fbb218c0] + BSON v0.2.3
  [b99e7846] + BinaryProvider v0.5.4
  [34da2185] + Compat v2.1.0
  [a93c6f00] + DataFrames v0.18.2
  [31c24e10] + Distributions v0.20.0
  [8f5d6c58] + EzXML v0.9.1
  [9da8a3cd] + JLSO v1.0.0
  [f28f55f0] + Memento v0.12.1
  [78c3b35d] + Mocking v0.5.7
  [f269a46b] + TimeZones v0.9.1
Updating `/tmp/jl_YCfgGu/Manifest.toml`
  [7d9fca2a] + Arpack v0.4.0
  [68821587] + Arpack_jll v3.5.0+3
  [56f22d72] + Artifacts v1.3.0
  [39de3d68] + AxisArrays v0.3.0
  [fbb218c0] + BSON v0.2.3
  [9e28174c] + BinDeps v0.8.10
  [b99e7846] + BinaryProvider v0.5.4
  [324d7699] + CategoricalArrays v0.7.7
  [34da2185] + Compat v2.1.0
  [e66e0078] + CompilerSupportLibraries_jll v0.3.4+0
  [9a962f9c] + DataAPI v1.10.0
  [a93c6f00] + DataFrames v0.18.2
  [864edb3b] + DataStructures v0.17.20
  [e2d170a0] + DataValueInterfaces v1.0.0
  [31c24e10] + Distributions v0.20.0
  [8f5d6c58] + EzXML v0.9.1
  [8197267c] + IntervalSets v0.3.2
  [c8e1da08] + IterTools v1.4.0
  [82899510] + IteratorInterfaceExtensions v1.0.0
  [692b3bcd] + JLLWrappers v1.4.1
  [9da8a3cd] + JLSO v1.0.0
  [682c06a0] + JSON v0.21.3
  [f28f55f0] + Memento v0.12.1
  [e1d29d7a] + Missings v0.4.5
  [78c3b35d] + Mocking v0.5.7
  [4536629a] + OpenBLAS_jll v0.3.9+5
  [bac558e1] + OrderedCollections v1.4.1
  [90014a1f] + PDMats v0.9.12
  [69de0a69] + Parsers v2.3.1
  [2dfb63ee] + PooledArrays v0.5.3
  [21216c6a] + Preferences v1.3.0
  [1fd47b50] + QuadGK v2.4.2
  [b3c3ace0] + RangeArrays v0.3.2
  [189a3867] + Reexport v0.2.0
  [79098fc4] + Rmath v0.5.1
  [a2af1166] + SortingAlgorithms v0.3.1
  [276daf66] + SpecialFunctions v0.7.2
  [2913bbd2] + StatsBase v0.30.0
  [4c63d2b9] + StatsFuns v0.8.0
  [cea106d9] + Syslogs v0.3.0
  [fa267f1f] + TOML v1.0.3
  [3783bdb8] + TableTraits v1.0.1
  [bd369af6] + Tables v0.2.11
  [f269a46b] + TimeZones v0.9.1
  [30578b45] + URIParser v0.4.1
  [2a0f44e3] + Base64
  [ade2ca70] + Dates
  [8bb1440f] + DelimitedFiles
  [8ba89e20] + Distributed
  [9fa8497b] + Future
  [b77e0a4c] + InteractiveUtils
  [76f85450] + LibGit2
  [8f399da3] + Libdl
  [37e2e46d] + LinearAlgebra
  [56ddb016] + Logging
  [d6f4376e] + Markdown
  [a63ad114] + Mmap
  [44cfe95a] + Pkg
  [de0858da] + Printf
  [9abbd945] + Profile
  [3fa0cd96] + REPL
  [9a3f8284] + Random
  [ea8e919c] + SHA
  [9e88b42a] + Serialization
  [1a1011a3] + SharedArrays
  [6462fe0b] + Sockets
  [2f01184e] + SparseArrays
  [10745b16] + Statistics
  [4607b0f0] + SuiteSparse
  [8dfed614] + Test
  [cf7118a7] + UUIDs
  [4ec0a83e] + Unicode
 Activating environment at `~/work/JLSO.jl/JLSO.jl/docs/Project.toml`
 Activating new environment at `/tmp/jl_G4IeZu/Project.toml`
 Activating environment at `~/work/JLSO.jl/JLSO.jl/docs/Project.toml`

In the above case, the project and manifest is only generated for the first file and reused for all subsequent files.