Assets/Resources

Flutter allows you to bundle assets (graphics, sounds, config files...) along with your flutter application however dart cli applications do not have this ability.
DCli provides a set of asset management tools and an api to work around this limitation.
DCli refers to assets as 'resources' to differentiate them from flutter assets.
If you use resources in a package that will be publish to pub.dev, remember there is a 10MB limit on the entire dart package.
DCli does this by packaging a resource into a .dart library and then providing an api that allows you to unpack the resources at runtime.
The dcli pack command base64 encodes each file and writes them as a multi-line string into a dart library under src/dcli/resource. The name of the dart library is randomly generated.
The pack command also creates a register of the packed libraries in src/dcli/resource/generated/resource_registry.g.dart.
DCli expects all resources to located within your dart project under:
1
<project root>/resource
Copied!
Packing resources
To pack your resources run:
1
dcli pack
Copied!
The 'pack' command will scan the '<project root>/resource' directory and all subdirectories. Each file that it finds will be converted to a dart library under:
1
<project root>/lib/src/dcli/resource/generated
Copied!
Each library name is generated using a md5 hash prefixed with the letter 'A' to make a valid class name. The library name is of the form A<md5hash>.g.dart
So the following resources:
1
<project root>/resource
2
                    /images/photo.png
3
                    /data/zips/installer.zip
Copied!
Will result in to:
1
<project root>/lib/src/dcli/resource/generated
2
                            /resource_registry.g.dart
3
                            /A21302b1b380201578fc8ce748f5d9ac8.g.dart
4
                            /A49bc9b7e40a7f3042a5bbb3e476b4dc4.g.dart
Copied!
The contents of each resource is base64 encoded into a multi-line string. So the photo.png.dart file will something look like:
1
class A21302b1b380201578fc8ce748f5d9ac8 extends PackedResource {
2
  /// PackedResource - local_batman.yaml
3
  const A21302b1b380201578fc8ce748f5d9ac8();
4
​
5
  /// A hash of the resource (pre packed) calculated by
6
  /// [calculateHash].
7
  /// This hash can be used to check if the resource needs to
8
  /// be updated on the target system.
9
  /// Use :
10
  /// ```dart
11
  ///   calculateHash(pathToResource).hexEncode() == packResource.checksum
12
  /// ```
13
  /// to compare the checksum of the local file with
14
  /// this checksum
15
  @override
16
  String get checksum =>
17
      '14189a469cf7f78af8cd8d4e03815ea72412cea6cbe94779a8db9f736e147300';
18
​
19
  /// <package>/resource relative path to the original resource.
20
  @override
21
  String get originalPath => 'lphoto.png';
22
​
23
  @override
24
  String get content => '''
25
bG9nUGF0aDogL3Zhci9sb2cvYmF0bWFuLmxvZwoKZW1haWxfc2VydmVyX2hvc3Q6IGxvY2FsaG9zdApl
26
bWFpbF9zZXJ2ZXJfcG9ydDogMjUKZW1haW
Copied!
Resource Registry
As part of the packing process DCli also creates a registry of the packed resources. This is done by creating a dart library called:
 <project root>/lib/src/dcli/resource/generated/resource_registry.g.dart
The contents of the 'resource_registry.dart' are of the form.
1
// ignore: prefer_relative_imports
2
import 'package:dcli/dcli.dart';
3
import 'Bbbcdcbeeff.g.dart';
4
import 'Bfbbcabcfec.g.dart';
5
​
6
/// GENERATED -- GENERATED
7
///
8
/// DO NOT MODIFIY
9
///
10
/// This script is generated via [Resource.pack()].
11
///
12
/// GENERATED - GENERATED
13
​
14
class ResourceRegistry {
15
  /// Map of the packed files.
16
  /// Use the path of a packed file (relative to the resource directory)
17
  /// to access the packed resource and then call [PackedResource].unpack()
18
  /// to unpack the file.
19
  /// ```dart
20
  /// ResourceRegistry.resources['batman.yaml']
21
  ///     .unpack(join(HOME, '.mysettings', 'batman.yaml'));
22
  /// ```
23
  static const resources = <String, PackedResource>{
24
    'local_batman.yaml': A21302b1b380201578fc8ce748f5d9ac8(),
25
    'docker_batman.yaml': A49bc9b7e40a7f3042a5bbb3e476b4dc4(),
26
  };
27
}
28
​
Copied!
Unpacking resources
DCli provides an api that allows your script to unpack its resources at run time.
1
ResourceRegistry().resources['<relative filename>'].unpack(String localPath)
Copied!
The resources field is a map and the key to the map is the original path to the packed file 'relative' to the resources directory.
e.g.
1
  const filename = 'PXL_20211104_224740653.jpg';
2
  
3
  final jpegResource = ResourceRegistry.resources[filename];
4
  
5
  final pathToConfigs = join(HOME, '.myapp');
6
  if (!exists(pathToConfigs)
7
  {
8
    createDir(pathToConfigs);
9
  }
10
  jpegResource!.unpack(join(pathToConfigs, filename);
11
​
Copied!
To unpack the resources on the target system use the ResourceRegistry class.
The ResourceRegistory.resources field is a map of the packed resources. The key is the path of the original resource file relative to the resource directory. 
Use the .unpack method to unpack your resource to a local path on the target system.
1
ResourceRegistry.resources['rules.yaml']
2
    .unpack(join(HOME, '.mysettings', 'rules.yaml'));
Copied!
The values in the resources map is a PackedResources. The PackedResource includes a checksum field. The checksum can be used to see if the expanded resource is the same as the packed resource. You can use this to determine if you need to upgrade the unpacked resource with the latest packed one.
​
1
if (calculateHash(pathToResource).hexEncode() != packResource.checksum)
2
{
3
    /// unpack the latest version of the resource.
4
}
Copied!
External Resources
You can also pack resources that are external to your project by creating a pack.yaml file under your project's tool/dcli directory.
The pack.yaml file allows you to specify a number of files and/or directories and their virtual mount point within the resource directory.
1
externals:
2
  - external:
3
    path: ../template/basic
4
    mount: template/basic
5
  - external:
6
    path: ../template/cmd_args
7
    mount: template/cmd_args
8
  - external:
9
    path: ../template/find
10
    mount: template/find
11
  - external:
12
    path: ../template/hello_world
13
    mount: template/hello_world
Copied!
The path for each external may be a file or a directory. If path is a directory then the directory is included recursively.
The mount point is a virtual location within the project resource directory. It may not overlap any actual files/paths in the project resource directory.
To unpack external resources you use the mount point as the key into the ResourceRegistry.
Limits
If you plan on publishing your project to pub.dev be aware that pub.dev has a maximum package size of 10MB.
The base64 encoding process increases the file size by about 33%.
For apps that you deploy locally the limits are not documented but are probably constrained by your systems memory - so fairly large.
 
Automating packing of resources
If you use pub_release to publish to pub.dev then you can create a pre-release hook to have pub_release package your resources.

Tour - Previous

The evils of CD

Next - Tour

Cross Platform

Last modified 5mo ago

Copy link

Contents

Automating packing of resources