1$NetBSD: README,v 1.1.1.1 2001/10/26 06:50:48 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 20Support for the following file systems maybe be added in the future 21 ext2fs Linux EXT2 file system 22 fat MS-DOS `FAT' file system (FAT12, FAT16, FAT32) 23 cd9660 ISO 9660 file system 24 25Various file system independent parameters and contraints can be 26specified, such as: 27 - minimum file system size (in KB) 28 - maximum file system size (in KB) 29 - free inodes 30 - free blocks (in KB) 31 - mtree(8) specification file containing permissions and ownership 32 to use in image, overridding the settings in the directory tree 33 - file containing list of files to specifically exclude or include 34 - fnmatch(3) pattern of filenames to exclude or include 35 - endianness of target file system 36 37File system specific parameters can be given as well, with a command 38line option such as "-o fsspeccific-options,comma-separated". 39For example, ffs would allow tuning of: 40 - block & fragement size 41 - cylinder groups 42 - number of blocks per inode 43 - minimum free space 44 45Other file systems might have controls on how to "munge" file names to 46fit within the constraints of the target file system. 47 48Exit codes: 49 0 all ok 50 1 fatal error 51 2 some files couldn't be added during image creation 52 (bad perms, missing file, etc). image will continue 53 to be made 54 55 56Implementation overview: 57------------------------ 58 59The implementation must allow for easy addition of extra file systems 60with minimal changes to the file system independent sections. 61 62The main program will: 63 - parse the options, including calling fs-specific routines to 64 validate fs-specific options 65 - walk the tree, building up a data structure which represents 66 the tree to stuff into the image. The structure will 67 probably be a similar tree to what mtree(8) uses internally; 68 a linked list of entries per directory with a child pointer 69 to children of directories. ".." won't be stored in the list; 70 the fs-specific tree walker should add this if required by the fs. 71 this builder have the smarts to handle hard links correctly. 72 - (optionally) Change the permissions in the tree according to 73 the mtree(8) specfile 74 - Call an fs-specific routine to build the image based on the 75 data structures. 76 77Each fs-specific module should have the following external interfaces: 78 79 parse_options parse the string for fs-specific options, feeding 80 errors back to the user as appropriate 81 82 make_fs take the data structures representing the 83 directory tree and fs parameters, 84 validate that the parameters are valid 85 (e.g, the requested image will be large enough), 86 create the image, and 87 populate the image 88 89 90ffs implementation 91------------------ 92 93In the ffs case, we can leverage off sbin/newfs/mkfs.c to actually build 94the image. When building and populating the image, the implementation 95can be greatly simplified if some assumptions are made: 96 - the total required size (in blocks and inodes) is determined 97 as part of the validation phase 98 - a "file" (including a directory) has a known size, so 99 support for growing a file is not necessary 100 101Two underlying primitives are provided: 102 make_inode create an inode, returning the inode number 103 104 write_file write file (from memory if DIR, file descriptor 105 if FILE or SYMLINK), referencing given inode. 106 it is smart enough to know if a short symlink 107 can be stuffed into the inode, etc. 108 109When creating a directory, the directory entries in the previously 110built tree data structure is scanned and built in memory so it can 111be written entirely as a single write_file() operation. 112