[physfs] Impending PhysicsFS 3.0.0...
Ryan C. Gordon
icculus at icculus.org
Tue Aug 15 02:52:43 EDT 2017
( This work was funded by my Patreon! If you like me working on things
like PhysicsFS and other useful pieces of code, consider throwing some
money in the pot: https://patreon.com/icculus )
So I knuckled down and pushed hard to get the PhysicsFS development
branch where I want it for a major-version release.
Now it's ready to go beta!
PhysicsFS 2.1.1, which will stabilize into 3.0.0, is ready for you to
test. It should be safe for anyone on any official release of PhysicsFS
to update: the API has been expanded over time, and functions have been
deprecated, but we are still source and binary compatible with programs
written against PhysicsFS 1.0.0. In theory, you can drop in a new build
and it'll Just Work.
Please try the latest in revision control with your apps and games and
report issues. A lot of code changed pretty quickly, so it's possible
obvious things are broken (and easy to fix), so feedback is _extremely_
It's hard to quantify everything that changed, because an enormous
amount of reworking went on behind the scenes, files got renamed a
bunch, etc. If you want _specifics_, pull the latest from Mercurial and
run "hg log -b default -r 5cabc31eb563:3396e6dd19fb" to get every commit
involved, but I'll summarize the best things here:
- PhysicsFS now is super-easy to build. You can usually just drop all
the C files into your project and compile it with everything else
without any magic configuration step. The CMake file is still there and
useful for packaging, etc, but it's 100% optional.
- ZIP files can now use the newer zip64 format.
- ZIP files may be password-protected. As the PkWare specs specify, each
file in the .zip may have a different password, so you call
PHYSFS_openRead(a, "file_that_i_want.txt$PASSWORD") to make it work.
Note that this is a wildly insecure way to protect your app's data, both
in how you'd have to manage passwords and that "traditional" PkWare
crypto is not really hardened anyhow. But if you have a basic
password-protected archive, PhysicsFS can get into it now!
- 7zip support has been rewritten and improved.
- ISO9660 archives are now supported.
- VDF (Gothic/Gothic2) archives are now supported.
- SLB (Independence War) archives are now supported.
- Everything behind the scenes now uses an abstract i/o interface
(PHYSFS_Io) instead of talking directly to files, and this interface is
available to applications. This allows you to mount anything as an
archive that you can wrap in a PHYSFS_Io, through the new
PHYSFS_mountIo() function. The obvious and most useful implementations
are already implemented for you behind the scenes on top of PHYSFS_Io:
PHYSFS_mountMemory() to mount an archive that's in a block of RAM, and
PHYSFS_mountHandle() to mount from a PHYSFS_File*...that is to say: you
now have an interface to do archives inside archives.
- The abstract interface that PhysicsFS uses to talk to archives
(PHYSFS_Archiver) is now public, so apps can implement their own
archivers and register them into the system. If you have a custom
archive format for your app, you can plug it into PhysicsFS at runtime
without modifying PhysicsFS itself.
- There's now a PHYSFS_getPrefDir() to figure out where it is safe to
write files on a given platform. This is usually a per-user,
per-application space, and should be used instead of
PHYSFS_getUserDir(). It might report something under
~/Library/Application Support on a Mac, somewhere under AppData for
Windows, or ~/.local/share on Linux, etc.
- There's now a PHYSFS_unmount() to match 2.0.0's PHYSFS_mount().
- There's now a PHYSFS_utf8FromUtf16(), so stop using
- There's now PHYSFS_utf8stricmp() for case-insensitive UTF-8 string
comparison, in case you need to compare filenames.
- Enumerating files can now report errors, instead of quietly dropping
files when there were problems. Enumeration callbacks can now return
results too ("keep going", "stop enumerating, no error I just got what I
needed", "something went wrong, stop and return an error to the app").
- There is now a PHYSFS_stat() call that returns metadata on a specific
file as a whole instead of using PHYSFS_isDirectory(),
PHYSFS_getLastModTime(), etc separately).
- There's now a PHYSFS_readBytes() function that operates more like Unix
read()...the older PHYSFS_read() operates more like ANSI C's fread(),
but had undefined behavior if it reads half an object. There is also an
- Errors are now reported by numeric codes your app can process (there's
a function to turn them into human readable strings). Apps can set the
per-thread error code now, too, which is useful if you're writing an
PHYSFS_Archiver or PHYSFS_Io.
- The OS/2 port has Unicode support now.
- The Windows port now uses UTF-16 for Unicode instead of UCS-2, and
dropped the ANSI fallbacks (so among other hurdles, you'll need to bring
your own UNICOWS.DLL if you want Win95 support still).
- Lots of improvements, redesigns, bug fixes, corner cases, and
- There's now a buildbot that makes sure this builds across two dozen
different targets on every commit:
- New platforms: iOS, Android, Emscripten, WinRT (UWP, Windows Phone,
Windows Store), Win64, QNX, Solaris, Hurd, Debian/kFreeBSD, ArcaOS,
- Dropped platforms: BeOS (Haiku is still supported), Windows CE
(Windows Phone is supported), Windows 95/98/ME (WinXP and later are
supported) MacOS Classic (macOS and iOS are supported). Even these might
work with minor patches if there's an urgent demand.
- Probably many other things.
That's all: please enjoy! And please test and report back!
More information about the physfs