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