README
1$NetBSD: README,v 1.4 2009/01/03 08:25:35 lukem Exp $
2
3makefs - build a file system image from a directory tree
4
5NOTES:
6
7 * This tool uses modified local copies of source found in other
8 parts of the tree. This is intentional.
9
10 * makefs is a work in progress, and subject to change.
11
12
13user overview:
14--------------
15
16makefs creates a file system image from a given directory tree.
17the following file system types can be built:
18 ffs BSD fast file system
19 cd9660 ISO 9660 file system
20 v7fs 7th edition(V7) file system
21
22Support for the following file systems maybe be added in the future
23 ext2fs Linux EXT2 file system
24 fat MS-DOS `FAT' file system (FAT12, FAT16, FAT32)
25
26Various file system independent parameters and contraints can be
27specified, such as:
28 - minimum file system size (in KB)
29 - maximum file system size (in KB)
30 - free inodes
31 - free blocks (in KB)
32 - mtree(8) specification file containing permissions and ownership
33 to use in image, overridding the settings in the directory tree
34 - file containing list of files to specifically exclude or include
35 - fnmatch(3) pattern of filenames to exclude or include
36 - endianness of target file system
37
38File system specific parameters can be given as well, with a command
39line option such as "-o fsspeccific-options,comma-separated".
40For example, ffs would allow tuning of:
41 - block & fragment size
42 - cylinder groups
43 - number of blocks per inode
44 - minimum free space
45
46Other file systems might have controls on how to "munge" file names to
47fit within the constraints of the target file system.
48
49Exit codes:
50 0 all ok
51 1 fatal error
52 2 some files couldn't be added during image creation
53 (bad perms, missing file, etc). image will continue
54 to be made
55
56
57Implementation overview:
58------------------------
59
60The implementation must allow for easy addition of extra file systems
61with minimal changes to the file system independent sections.
62
63The main program will:
64 - parse the options, including calling fs-specific routines to
65 validate fs-specific options
66 - walk the tree, building up a data structure which represents
67 the tree to stuff into the image. The structure will
68 probably be a similar tree to what mtree(8) uses internally;
69 a linked list of entries per directory with a child pointer
70 to children of directories. ".." won't be stored in the list;
71 the fs-specific tree walker should add this if required by the fs.
72 this builder have the smarts to handle hard links correctly.
73 - (optionally) Change the permissions in the tree according to
74 the mtree(8) specfile
75 - Call an fs-specific routine to build the image based on the
76 data structures.
77
78Each fs-specific module should have the following external interfaces:
79
80 prepare_options optional file system specific defaults that need to be
81 setup before parsing fs-specific options.
82
83 parse_options parse the string for fs-specific options, feeding
84 errors back to the user as appropriate
85
86 cleanup_options optional file system specific data that need to be
87 cleaned up when done with this filesystem.
88
89 make_fs take the data structures representing the
90 directory tree and fs parameters,
91 validate that the parameters are valid
92 (e.g, the requested image will be large enough),
93 create the image, and
94 populate the image
95
96prepare_options and cleanup_options are optional and can be NULL.
97
98NOTE: All file system specific options are referenced via the fs_specific
99pointer from the fsinfo_t strucutre. It is up to the filesystem to allocate
100and free any data needed for this via the prepare and cleanup callbacks.
101
102Each fs-specific module will need to add it's routines to the dispatch array
103in makefs.c and add prototypes for these to makefs.h
104
105All other implementation details should not need to change any of the
106generic code.
107
108ffs implementation
109------------------
110
111In the ffs case, we can leverage off sbin/newfs/mkfs.c to actually build
112the image. When building and populating the image, the implementation
113can be greatly simplified if some assumptions are made:
114 - the total required size (in blocks and inodes) is determined
115 as part of the validation phase
116 - a "file" (including a directory) has a known size, so
117 support for growing a file is not necessary
118
119Two underlying primitives are provided:
120 make_inode create an inode, returning the inode number
121
122 write_file write file (from memory if DIR, file descriptor
123 if FILE or SYMLINK), referencing given inode.
124 it is smart enough to know if a short symlink
125 can be stuffed into the inode, etc.
126
127When creating a directory, the directory entries in the previously
128built tree data structure is scanned and built in memory so it can
129be written entirely as a single write_file() operation.
130