-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | A tool and library for building virtual machine images. -- @package b9 @version 0.2.5 -- | Utility module to extract a primary partition from an MBR partition on -- a raw image file. module B9.MBR getPartition :: Int -> FilePath -> IO (Word64, Word64) data PrimaryPartition PrimaryPartition :: !Word8 -> !CHS -> !Word8 -> !CHS -> !Word32 -> !Word32 -> PrimaryPartition primPartStatus :: PrimaryPartition -> !Word8 primPartChsStart :: PrimaryPartition -> !CHS primPartPartType :: PrimaryPartition -> !Word8 primPartChsEnd :: PrimaryPartition -> !CHS primPartLbaStart :: PrimaryPartition -> !Word32 primPartSectors :: PrimaryPartition -> !Word32 data MBR MBR :: !PrimaryPartition -> !PrimaryPartition -> !PrimaryPartition -> !PrimaryPartition -> MBR mbrPart1 :: MBR -> !PrimaryPartition mbrPart2 :: MBR -> !PrimaryPartition mbrPart3 :: MBR -> !PrimaryPartition mbrPart4 :: MBR -> !PrimaryPartition data CHS CHS :: !Word8 -> !Word8 -> !Word8 -> CHS chsH :: CHS -> !Word8 chs_CUpper2_S :: CHS -> !Word8 chs_CLower8 :: CHS -> !Word8 instance Show CHS instance Show PrimaryPartition instance Show MBR -- | Function to find the file offsets of primary partitions in raw disk -- images. Currently only MBR partitions are supported. See MBR module B9.PartitionTable getPartition :: Int -> FilePath -> IO (Word64, Word64, Word64) -- | Some QuickCheck utility functions. module B9.QCUtil arbitraryEnv :: Arbitrary a => Gen [(String, a)] halfSize :: Gen a -> Gen a smaller :: Gen a -> Gen a arbitraryFilePath :: Gen FilePath arbitraryLetter :: Gen Char arbitraryLetterUpper :: Gen Char arbitraryLetterLower :: Gen Char arbitraryDigit :: Gen Char -- | Erlang term parser and pretty printer. module B9.Content.ErlTerms -- | Parse a subset of valid Erlang terms. It parses no maps and binaries -- are restricted to either empty binaries or binaries with a string. The -- input encoding must be restricted to ascii compatible 8-bit characters -- (e.g. latin-1 or UTF8). parseErlTerm :: String -> ByteString -> Either String SimpleErlangTerm -- | Convert an abstract Erlang term to a pretty byte string preserving the -- encoding. renderErlTerm :: SimpleErlangTerm -> ByteString -- | Simplified Erlang term representation. data SimpleErlangTerm ErlString :: String -> SimpleErlangTerm ErlFloat :: Double -> SimpleErlangTerm ErlNatural :: Integer -> SimpleErlangTerm ErlAtom :: String -> SimpleErlangTerm ErlChar :: Char -> SimpleErlangTerm ErlBinary :: String -> SimpleErlangTerm ErlList :: [SimpleErlangTerm] -> SimpleErlangTerm ErlTuple :: [SimpleErlangTerm] -> SimpleErlangTerm arbitraryErlSimpleAtom :: Gen SimpleErlangTerm arbitraryErlString :: Gen SimpleErlangTerm arbitraryErlNumber :: Gen SimpleErlangTerm arbitraryErlNatural :: Gen SimpleErlangTerm arbitraryErlFloat :: Gen SimpleErlangTerm arbitraryErlNameChar :: Gen Char instance Typeable SimpleErlangTerm instance Eq SimpleErlangTerm instance Ord SimpleErlangTerm instance Read SimpleErlangTerm instance Show SimpleErlangTerm instance Data SimpleErlangTerm instance Arbitrary SimpleErlangTerm -- | Definition of Script and functions to convert Scripts to -- bash scripts. module B9.ShellScript -- | Convert script to bash-shell-script written to file -- and make file executable. writeSh :: FilePath -> Script -> IO () -- | Check if a script has the same effect as NoOP emptyScript :: Script -> Bool data CmdVerbosity Debug :: CmdVerbosity Verbose :: CmdVerbosity OnlyStdErr :: CmdVerbosity Quiet :: CmdVerbosity data Cwd Cwd :: FilePath -> Cwd NoCwd :: Cwd data User User :: String -> User NoUser :: User data Script In :: FilePath -> [Script] -> Script As :: String -> [Script] -> Script IgnoreErrors :: Bool -> [Script] -> Script Verbosity :: CmdVerbosity -> [Script] -> Script Begin :: [Script] -> Script Run :: FilePath -> [String] -> Script NoOP :: Script instance Typeable CmdVerbosity instance Typeable Script instance Show CmdVerbosity instance Read CmdVerbosity instance Data CmdVerbosity instance Eq CmdVerbosity instance Show Script instance Read Script instance Data Script instance Eq Script instance Show Cwd instance Read Cwd instance Show User instance Read User instance Show Cmd instance Read Cmd instance Monoid Script -- | Data types that describe all B9 relevant elements of virtual machine -- disk images. module B9.DiskImages -- | Build target for disk images; the destination, format and size of the -- image to generate, as well as how to create or obtain the image before -- a VmScript is executed with the image mounted at a -- MountPoint. data ImageTarget ImageTarget :: ImageDestination -> ImageSource -> MountPoint -> ImageTarget -- | A mount point or NotMounted data MountPoint MountPoint :: FilePath -> MountPoint NotMounted :: MountPoint -- | The destination of an image. data ImageDestination -- | Create the image and some meta data so that other builds can use them -- as ImageSources via From. Share :: String -> ImageType -> ImageResize -> ImageDestination -- | DEPRECATED Export a raw image that can directly be booted. LiveInstallerImage :: String -> FilePath -> ImageResize -> ImageDestination -- | Write an image file to the path in the first argument., possible -- resizing it, LocalFile :: Image -> ImageResize -> ImageDestination -- | Do not export the image. Usefule if the main objective of the b9 build -- is not an image file, but rather some artifact produced by executing -- by a containerize build. Transient :: ImageDestination -- | Specification of how the image to build is obtained. data ImageSource -- | Create an empty image file having a file system label (first -- parameter), a file system type (e.g. Ext4) and an -- ImageSize EmptyImage :: String -> FileSystem -> ImageType -> ImageSize -> ImageSource -- | DEPRECATED CopyOnWrite :: Image -> ImageSource -- | Clone an existing image file; if the image file contains partitions, -- select the partition to use, b9 will extract that partition by reading -- the offset of the partition from the partition table and extract it -- using dd. SourceImage :: Image -> Partition -> ImageResize -> ImageSource -- | Use an image previously shared by via Share. From :: String -> ImageResize -> ImageSource -- | The partition to extract. data Partition -- | There is no partition table on the image NoPT :: Partition -- | Extract partition n n must be in 0..3 Partition :: Int -> Partition -- | A vm disk image file consisting of a path to the image file, and the -- type and file system. data Image Image :: FilePath -> ImageType -> FileSystem -> Image data ImageType Raw :: ImageType QCow2 :: ImageType Vmdk :: ImageType data FileSystem NoFileSystem :: FileSystem Ext4 :: FileSystem ISO9660 :: FileSystem VFAT :: FileSystem data ImageSize ImageSize :: Int -> SizeUnit -> ImageSize data SizeUnit B :: SizeUnit KB :: SizeUnit MB :: SizeUnit GB :: SizeUnit -- | How to resize an image file. data ImageResize -- | Resize the image but not the file system. Note that a file -- system contained in the image file might be corrupted by this -- operation. To not only resize the image file but also the fil system -- contained in it, use Resize. ResizeImage :: ImageSize -> ImageResize -- | Resize an image and the contained file system. Resize :: ImageSize -> ImageResize -- | Resize an image and the contained file system to the smallest size to -- fit the contents of the file system. ShrinkToMinimum :: ImageResize -- | Do not change the image size. KeepSize :: ImageResize type Mounted a = (a, MountPoint) itImageDestination :: ImageTarget -> ImageDestination itImageMountPoint :: ImageTarget -> MountPoint isPartitioned :: Partition -> Bool getPartition :: Partition -> Int -- | Return the file name extension of an image file with a specific image -- format. imageFileExtension :: ImageType -> String changeImageFormat :: ImageType -> Image -> Image changeImageDirectory :: FilePath -> Image -> Image -- | SharedImage holds all data necessary to identify an image -- shared. Shared images are stored in Repositorys. data SharedImage SharedImage :: SharedImageName -> SharedImageDate -> SharedImageBuildId -> ImageType -> FileSystem -> SharedImage -- | Return the name of a shared image. siName :: SharedImage -> String -- | Shared images are orderd by name, build date and build id newtype SharedImageName SharedImageName :: String -> SharedImageName newtype SharedImageDate SharedImageDate :: String -> SharedImageDate newtype SharedImageBuildId SharedImageBuildId :: String -> SharedImageBuildId -- | Return the disk image of an sharedImage sharedImageImage :: SharedImage -> Image -- | Calculate the path to the text file holding the serialized -- SharedImage relative to the directory of shared images in a -- repository. sharedImageFileName :: SharedImage -> FilePath sharedImagesRootDirectory :: FilePath sharedImageFileExtension :: String instance Typeable MountPoint instance Typeable Partition instance Typeable ImageType instance Typeable FileSystem instance Typeable Image instance Typeable SizeUnit instance Typeable ImageSize instance Typeable ImageResize instance Typeable ImageSource instance Typeable ImageDestination instance Typeable ImageTarget instance Show MountPoint instance Read MountPoint instance Data MountPoint instance Eq MountPoint instance Eq Partition instance Show Partition instance Read Partition instance Data Partition instance Eq ImageType instance Read ImageType instance Data ImageType instance Show ImageType instance Eq FileSystem instance Show FileSystem instance Read FileSystem instance Data FileSystem instance Eq Image instance Show Image instance Read Image instance Data Image instance Eq SizeUnit instance Show SizeUnit instance Read SizeUnit instance Ord SizeUnit instance Data SizeUnit instance Eq ImageSize instance Show ImageSize instance Read ImageSize instance Data ImageSize instance Eq ImageResize instance Show ImageResize instance Read ImageResize instance Data ImageResize instance Show ImageSource instance Read ImageSource instance Data ImageSource instance Eq ImageSource instance Read ImageDestination instance Show ImageDestination instance Data ImageDestination instance Eq ImageDestination instance Read ImageTarget instance Show ImageTarget instance Data ImageTarget instance Eq ImageTarget instance Eq SharedImageName instance Ord SharedImageName instance Read SharedImageName instance Show SharedImageName instance Eq SharedImageDate instance Ord SharedImageDate instance Read SharedImageDate instance Show SharedImageDate instance Eq SharedImageBuildId instance Ord SharedImageBuildId instance Read SharedImageBuildId instance Show SharedImageBuildId instance Eq SharedImage instance Read SharedImage instance Show SharedImage instance Ord SharedImage -- | Data types describing the execution environment of virtual machine -- builds. ExecEnv, Resources and SharedDirectory -- describe how B9.LibVirtLXC should configure and execute build -- scripts, as defined in B9.ShellScript and B9.Vm. module B9.ExecEnv data ExecEnv ExecEnv :: String -> [Mounted Image] -> [SharedDirectory] -> Resources -> ExecEnv envName :: ExecEnv -> String envImageMounts :: ExecEnv -> [Mounted Image] envSharedDirectories :: ExecEnv -> [SharedDirectory] envResources :: ExecEnv -> Resources data Resources Resources :: RamSize -> Int -> CPUArch -> Resources maxMemory :: Resources -> RamSize cpuCount :: Resources -> Int cpuArch :: Resources -> CPUArch noResources :: Resources data SharedDirectory SharedDirectory :: FilePath -> MountPoint -> SharedDirectory SharedDirectoryRO :: FilePath -> MountPoint -> SharedDirectory SharedSources :: MountPoint -> SharedDirectory data CPUArch X86_64 :: CPUArch I386 :: CPUArch data RamSize RamSize :: Int -> SizeUnit -> RamSize AutomaticRamSize :: RamSize instance Typeable SharedDirectory instance Typeable CPUArch instance Typeable RamSize instance Typeable Resources instance Read SharedDirectory instance Show SharedDirectory instance Data SharedDirectory instance Eq SharedDirectory instance Read CPUArch instance Show CPUArch instance Data CPUArch instance Eq CPUArch instance Eq RamSize instance Read RamSize instance Show RamSize instance Ord RamSize instance Data RamSize instance Read Resources instance Show Resources instance Data Resources instance Monoid RamSize instance Monoid CPUArch instance Monoid Resources -- | Extensions to ConfigFile and utility functions for dealing with -- configuration in general and reading/writing files. module B9.ConfigUtils allOn :: (a -> Maybe Bool) -> a -> a -> Maybe Bool lastOn :: (a -> Maybe b) -> a -> a -> Maybe b data SystemPath Path :: FilePath -> SystemPath InHomeDir :: FilePath -> SystemPath InB9UserDir :: FilePath -> SystemPath InTempDir :: FilePath -> SystemPath resolve :: MonadIO m => SystemPath -> m FilePath ensureDir :: MonadIO m => FilePath -> m () readIniFile :: MonadIO m => SystemPath -> m ConfigParser getOptionM :: (Get_C a, Read a) => ConfigParser -> SectionSpec -> OptionSpec -> Maybe a getOption :: (Get_C a, Monoid a) => ConfigParser -> SectionSpec -> OptionSpec -> a getOptionOr :: (Get_C a, Read a) => ConfigParser -> SectionSpec -> OptionSpec -> a -> a data IniFileException IniFileException :: FilePath -> CPError -> IniFileException newtype UUID UUID :: (Word32, Word16, Word16, Word16, Word32, Word16) -> UUID randomUUID :: MonadIO m => m UUID tell :: (MonadIO m, Show a) => FilePath -> a -> m () consult :: (MonadIO m, Read a) => FilePath -> m a -- | Get all files from dir that is get ONLY files not directories getDirectoryFiles :: MonadIO m => FilePath -> m [FilePath] maybeConsult :: (MonadIO m, Read a) => Maybe FilePath -> a -> m a maybeConsultSystemPath :: (MonadIO m, Read a) => Maybe SystemPath -> a -> m a instance Typeable SystemPath instance Typeable ReaderException instance Typeable IniFileException instance Eq SystemPath instance Read SystemPath instance Show SystemPath instance Data SystemPath instance Show ReaderException instance Show IniFileException instance Read UUID instance Show UUID instance Eq UUID instance Ord UUID instance PrintfArg UUID instance Exception IniFileException instance Exception ReaderException -- | B9 has a concept of SharedImaged. Shared images can be pulled -- and pushed to/from remote locations via rsync+ssh. B9 also maintains a -- local cache; the whole thing is supposed to be build-server-safe, that -- means no two builds shall interfere with each other. This is -- accomplished by refraining from automatic cache updates from/to remote -- repositories. module B9.Repository data RemoteRepo RemoteRepo :: String -> FilePath -> SshPrivKey -> SshRemoteHost -> SshRemoteUser -> RemoteRepo remoteRepoRepoId :: RemoteRepo -> String newtype RepoCache RepoCache :: FilePath -> RepoCache newtype SshPrivKey SshPrivKey :: FilePath -> SshPrivKey newtype SshRemoteHost SshRemoteHost :: (String, Int) -> SshRemoteHost newtype SshRemoteUser SshRemoteUser :: String -> SshRemoteUser -- | Initialize the local repository cache directory. initRepoCache :: MonadIO m => SystemPath -> m RepoCache -- | Initialize the repository; load the corresponding settings from the -- config file, check that the priv key exists and create the -- correspondig cache directory. initRemoteRepo :: MonadIO m => RepoCache -> RemoteRepo -> m RemoteRepo -- | Check for existance of priv-key and make it an absolute path. remoteRepoCheckSshPrivKey :: MonadIO m => RemoteRepo -> m RemoteRepo -- | Return the cache directory for a remote repository relative to the -- root cache dir. remoteRepoCacheDir :: RepoCache -> String -> FilePath -- | Return the local repository directory. localRepoDir :: RepoCache -> FilePath -- | Persist a repo to a configuration file. writeRemoteRepoConfig :: RemoteRepo -> ConfigParser -> Either CPError ConfigParser getConfiguredRemoteRepos :: ConfigParser -> [RemoteRepo] -- | Load a repository from a configuration file that has been written by -- writeRepositoryToB9Config. lookupRemoteRepo :: [RemoteRepo] -> String -> Maybe RemoteRepo instance Typeable RepoCache instance Typeable SshPrivKey instance Typeable SshRemoteHost instance Typeable SshRemoteUser instance Typeable RemoteRepo instance Read RepoCache instance Show RepoCache instance Data RepoCache instance Read SshPrivKey instance Show SshPrivKey instance Data SshPrivKey instance Read SshRemoteHost instance Show SshRemoteHost instance Data SshRemoteHost instance Read SshRemoteUser instance Show SshRemoteUser instance Data SshRemoteUser instance Read RemoteRepo instance Show RemoteRepo instance Data RemoteRepo -- | Utility functions based on Template to offer $var -- variable expansion in string throughout a B9 artifact. module B9.Content.StringTemplate subst :: [(String, String)] -> String -> String substE :: [(String, String)] -> String -> Either String String substEB :: [(String, String)] -> ByteString -> Either String ByteString substFile :: MonadIO m => [(String, String)] -> FilePath -> FilePath -> m () substPath :: [(String, String)] -> SystemPath -> SystemPath readTemplateFile :: (MonadIO m, MonadReader Environment m) => SourceFile -> m ByteString -- | A wrapper around a file path and a flag indicating if template -- variable expansion should be performed when reading the file contents. data SourceFile Source :: SourceFileConversion -> FilePath -> SourceFile data SourceFileConversion NoConversion :: SourceFileConversion ExpandVariables :: SourceFileConversion data Environment Environment :: [(String, String)] -> Environment withEnvironment :: [(String, String)] -> ReaderT Environment m a -> m a instance Typeable SourceFileConversion instance Typeable SourceFile instance Read SourceFileConversion instance Show SourceFileConversion instance Data SourceFileConversion instance Eq SourceFileConversion instance Read SourceFile instance Show SourceFile instance Data SourceFile instance Eq SourceFile instance Arbitrary SourceFile -- | Definition of VmScript an artifact encapsulating several -- virtual machines disk images that can be mounted in an execution -- environment like B9.LibVirtLXC. A VmScript is embedded -- by in an ArtifactGenerator. module B9.Vm -- | Describe a virtual machine, i.e. a set up disk images to create and a -- shell script to put things together. data VmScript VmScript :: CPUArch -> [SharedDirectory] -> Script -> VmScript NoVmScript :: VmScript substVmScript :: [(String, String)] -> VmScript -> VmScript instance Typeable VmScript instance Read VmScript instance Show VmScript instance Data VmScript instance Eq VmScript -- | B9 produces not only VM-Images but also text documents such as -- configuration files required by virtual machines. This module is about -- creating and merging files containing parsable syntactic structures, -- such as most configuration files do. -- -- Imagine you would want to create a cloud-init 'user-data' file from a -- set of 'user-data' snippets which each are valid 'user-data' files in -- yaml syntax and e.g. a writefiles section. Now the goal is, -- for b9 to be able to merge these snippets into one, such that all -- writefiles sections are combined into a single writefile section. -- Another example is OTP/Erlang sys.config files. This type class is the -- greatest commonon denominator of types describing a syntax that can be -- parsed, concatenated e.g. like in the above example and rendered. The -- actual concatenation operation is the append from Monoid, i.e. like -- monoid but without the need for an empty element. module B9.Content.AST -- | Types of values that can be parsedrendered fromto -- ByteStrings. This class is used as basis for the -- ASTish class. class Semigroup a => ConcatableSyntax a decodeSyntax :: ConcatableSyntax a => FilePath -> ByteString -> Either String a encodeSyntax :: ConcatableSyntax a => a -> ByteString -- | Types of values that describe content, that can be created from an -- AST. class ConcatableSyntax a => ASTish a fromAST :: (ASTish a, CanRender c, Applicative m, Monad m, MonadIO m, MonadReader Environment m) => AST c a -> m a -- | Describe how to create structured content that has a tree-like -- syntactic structure, e.g. yaml, JSON and erlang-proplists. The first -- parameter defines a context into which the AST is -- embeded, e.g. B9.Content.Generator.Content'. The second parameter -- defines a specifix syntax, e.g ErlangPropList that the -- AST value generates. data AST c a -- | Create an object similar to a Json object. ASTObj :: [(String, AST c a)] -> AST c a -- | An array. ASTArr :: [AST c a] -> AST c a -- | Merge the nested elements, this is a very powerful tool that allows to -- combine several inputs in a smart and safe way, e.g. by merging the -- values of the same fields in yaml objects. ASTMerge :: [AST c a] -> AST c a ASTEmbed :: c -> AST c a ASTString :: String -> AST c a ASTParse :: SourceFile -> AST c a AST :: a -> AST c a -- | Types of values that can be rendered into a ByteString class CanRender c render :: (CanRender c, Functor m, Applicative m, MonadIO m, MonadReader Environment m) => c -> m ByteString instance Typeable AST instance (Read c, Read a) => Read (AST c a) instance (Show c, Show a) => Show (AST c a) instance (Data c, Data a) => Data (AST c a) instance (Eq c, Eq a) => Eq (AST c a) instance (Arbitrary c, Arbitrary a) => Arbitrary (AST c a) instance ConcatableSyntax ByteString -- | A wrapper around erlang and yaml syntax with a proplist-like behaviour -- in the ConcatableSyntax instances module B9.Content.ErlangPropList -- | A wrapper type around erlang terms with a Semigroup instance useful -- for combining sys.config files with OTP-application configurations in -- a list of the form of a proplist. data ErlangPropList ErlangPropList :: SimpleErlangTerm -> ErlangPropList instance Typeable ErlangPropList instance Read ErlangPropList instance Eq ErlangPropList instance Show ErlangPropList instance Data ErlangPropList instance ASTish ErlangPropList instance ConcatableSyntax ErlangPropList instance Semigroup ErlangPropList instance Arbitrary ErlangPropList -- | A wrapper around erlang and yaml syntax with a proplist-like behaviour -- in the ConcatableSyntax instances module B9.Content.YamlObject -- | A wrapper type around yaml values with a Semigroup instance useful for -- combining yaml documents describing system configuration like e.g. -- user-data. data YamlObject YamlObject :: Value -> YamlObject instance Eq YamlObject instance Arbitrary YamlObject instance ASTish YamlObject instance ConcatableSyntax YamlObject instance Semigroup YamlObject instance Show YamlObject instance Read YamlObject -- | The basic data structure that ties together syntax trees making them -- composable and addressable in B9 artifacts. module B9.Content.Generator data Content RenderErlang :: (AST Content ErlangPropList) -> Content RenderYaml :: (AST Content YamlObject) -> Content FromTextFile :: SourceFile -> Content instance Typeable Content instance Read Content instance Show Content instance Eq Content instance CanRender Content instance Arbitrary Content -- | Top-Level data types for B9 build artifacts. module B9.ArtifactGenerator -- | Artifacts represent the things B9 can build. A generator specifies -- howto generate parameterized, multiple artifacts. The general -- structure is: -- -- 
--   Let [ ... bindings ... ]
--       [ Sources
--           [ ... list all input files ... ]
--           [ Artifact ...
--           , Artifact ...
--           , Let [ ... ] [ ... ]
--           ]
--       ]
--
-- -- The reasons why Sources takes a list of -- ArtifactGenerators is that 1. this makes the value easier to -- read/write for humans 2. the sources are static files used in all -- children (e.g. company logo image) 3. the sources are parameterized by -- variables that bound to different values for each artifact, e.g. a -- template network config file which contains the host IP address. -- -- To bind such variables use Let, Each, LetX or -- EachT. -- -- String subtitution of these variables is done by -- B9.Content.StringTemplate. These variables can be used as value -- in nested Lets, in most file names/paths and in source files -- added with SourceFile data ArtifactGenerator -- | Add sources available to ArtifactAssemblys in nested artifact -- generators. Sources :: [ArtifactSource] -> [ArtifactGenerator] -> ArtifactGenerator -- | Bind variables, variables are avaible in nested generators. Let :: [(String, String)] -> [ArtifactGenerator] -> ArtifactGenerator -- | A Let where each variable is assigned to each value; the nested -- generator is executed for each permutation. -- -- 
--   LetX [("x", ["1","2","3"]), ("y", ["a","b"])] [..]
--
-- -- Is equal to: -- -- 
--   Let [] [
--     Let [("x", "1"), ("y", "a")] [..]
--     Let [("x", "1"), ("y", "b")] [..]
--     Let [("x", "2"), ("y", "a")] [..]
--     Let [("x", "2"), ("y", "b")] [..]
--     Let [("x", "3"), ("y", "a")] [..]
--     Let [("x", "3"), ("y", "b")] [..]
--   ]
--
LetX :: [(String, [String])] -> [ArtifactGenerator] -> ArtifactGenerator -- | Bind each variable to their first value, then each variable to the -- second value, etc ... and execute the nested generator in every step. -- LetX represents a product of all variables, whereas Each -- represents a sum of variable bindings - Each is more like a -- zip whereas LetX is more like a list comprehension. Each :: [(String, [String])] -> [ArtifactGenerator] -> ArtifactGenerator -- | The transposed verison of Each: Bind the variables in the first -- list to each a set of values from the second argument; execute the -- nested generators for each binding EachT :: [String] -> [[String]] -> [ArtifactGenerator] -> ArtifactGenerator -- | Generate an artifact defined by an ArtifactAssembly; the -- assembly can access the files created from the Sources and -- variables bound by Letish elements. An artifact has an instance -- id, that is a unique, human readable string describing the artifact to -- assemble. Artifact :: InstanceId -> ArtifactAssembly -> ArtifactGenerator EmptyArtifact :: ArtifactGenerator -- | Describe how input files for artifacts to build are obtained. The -- general structure of each constructor is FromXXX -- destination source data ArtifactSource -- | Copy a SourceFile potentially replacing variabled defined in -- Let-like parent elements. FromFile :: FilePath -> SourceFile -> ArtifactSource -- | Create a file from some Content FromContent :: FilePath -> Content -> ArtifactSource -- | Set the unix file permissions to all files generated by the -- nested list of ArtifactSources. SetPermissions :: Int -> Int -> Int -> [ArtifactSource] -> ArtifactSource -- | Assume a local directory as starting point for all relative source -- files in the nested ArtifactSources. FromDirectory :: FilePath -> [ArtifactSource] -> ArtifactSource -- | Specify an output directory for all the files generated by the nested -- ArtifactSources IntoDirectory :: FilePath -> [ArtifactSource] -> ArtifactSource -- | Deprecated Concatenate the files generated by the nested -- ArtifactSources. The nested, generated files are not written -- when they are concatenated. Concatenation :: FilePath -> [ArtifactSource] -> ArtifactSource -- | Identify an artifact. Deprecated TODO: B9 does not check if all -- instances IDs are unique. newtype InstanceId IID :: String -> InstanceId data ArtifactTarget CloudInitTarget :: CloudInitType -> FilePath -> ArtifactTarget VmImagesTarget :: ArtifactTarget data CloudInitType CI_ISO :: CloudInitType CI_VFAT :: CloudInitType CI_DIR :: CloudInitType -- | Define an output of a build. Assemblies are nested into -- ArtifactGenerators. They contain all the files defined by the -- Sources they are nested into. data ArtifactAssembly -- | Generate a cloud-init compatible directory, ISO- or VFAT image, -- as specified by the list of CloudInitTypes. Every item will use -- the second argument to create an appropriate file name, e.g. -- for the CI_ISO type the output is second_param.iso. CloudInit :: [CloudInitType] -> FilePath -> ArtifactAssembly -- | a set of VM-images that were created by executing a build script on -- them. VmImages :: [ImageTarget] -> VmScript -> ArtifactAssembly -- | A type representing the targets assembled by assemble from an -- ArtifactAssembly. There is a list of ArtifactTargets -- because e.g. a single CloudInit can produce upto three output -- files, a directory, an ISO image and a VFAT image. data AssembledArtifact AssembledArtifact :: InstanceId -> [ArtifactTarget] -> AssembledArtifact -- | The variable containing the instance id. Deprecated instanceIdKey :: String -- | The variable containing the buildId that identifies each execution of -- B9. For more info about variable substitution in source files see -- StringTemplate buildIdKey :: String -- | The variable containing the date and time a build was started. For -- more info about variable substitution in source files see -- StringTemplate buildDateKey :: String instance Typeable InstanceId instance Typeable CloudInitType instance Typeable ArtifactTarget instance Typeable AssembledArtifact instance Typeable ArtifactAssembly instance Read ArtifactSource instance Show ArtifactSource instance Eq ArtifactSource instance Read InstanceId instance Show InstanceId instance Data InstanceId instance Eq InstanceId instance Read CloudInitType instance Show CloudInitType instance Data CloudInitType instance Eq CloudInitType instance Read ArtifactTarget instance Show ArtifactTarget instance Data ArtifactTarget instance Eq ArtifactTarget instance Read AssembledArtifact instance Show AssembledArtifact instance Data AssembledArtifact instance Eq AssembledArtifact instance Read ArtifactAssembly instance Show ArtifactAssembly instance Data ArtifactAssembly instance Eq ArtifactAssembly instance Read ArtifactGenerator instance Show ArtifactGenerator instance Eq ArtifactGenerator instance Arbitrary CloudInitType instance Arbitrary ArtifactAssembly instance Arbitrary InstanceId instance Arbitrary ArtifactSource instance Arbitrary ArtifactGenerator instance Monoid ArtifactGenerator -- | Static B9 configuration. Read, write and merge configurable -- properties. The properties are independent of specific build targets. module B9.B9Config data B9Config B9Config :: Maybe LogLevel -> Maybe FilePath -> Maybe FilePath -> Bool -> ExecEnvType -> Maybe FilePath -> BuildVariables -> Bool -> SystemPath -> Maybe String -> B9Config verbosity :: B9Config -> Maybe LogLevel logFile :: B9Config -> Maybe FilePath buildDirRoot :: B9Config -> Maybe FilePath keepTempDirs :: B9Config -> Bool execEnvType :: B9Config -> ExecEnvType profileFile :: B9Config -> Maybe FilePath envVars :: B9Config -> BuildVariables uniqueBuildDirs :: B9Config -> Bool repositoryCache :: B9Config -> SystemPath repository :: B9Config -> Maybe String defaultB9ConfigFile :: SystemPath defaultB9Config :: B9Config getB9ConfigFile :: MonadIO m => Maybe SystemPath -> m FilePath writeB9Config :: MonadIO m => (Maybe SystemPath) -> ConfigParser -> m () writeInitialB9Config :: MonadIO m => (Maybe SystemPath) -> B9Config -> ConfigParser -> m () readB9Config :: MonadIO m => (Maybe SystemPath) -> m ConfigParser parseB9Config :: ConfigParser -> Either String B9Config data LogLevel LogTrace :: LogLevel LogDebug :: LogLevel LogInfo :: LogLevel LogError :: LogLevel LogNothing :: LogLevel data ExecEnvType LibVirtLXC :: ExecEnvType type BuildVariables = [(String, String)] instance Eq ExecEnvType instance Show ExecEnvType instance Ord ExecEnvType instance Read ExecEnvType instance Eq LogLevel instance Show LogLevel instance Ord LogLevel instance Read LogLevel instance Show B9Config instance Monoid B9Config -- | Definition of the B9 monad. It encapsulates logging, very basic -- command execution profiling, a reader for the B9.B9Config and -- access to the current build id, the current build directory and the -- artifact to build. -- -- This module is used by the _effectful_ functions in this library. module B9.B9Monad data B9 a run :: ConfigParser -> B9Config -> B9 a -> IO a traceL :: String -> B9 () dbgL :: String -> B9 () infoL :: String -> B9 () errorL :: String -> B9 () getConfigParser :: B9 ConfigParser getConfig :: B9 B9Config getBuildId :: B9 FilePath getBuildDate :: B9 String getBuildDir :: B9 FilePath getExecEnvType :: B9 ExecEnvType getSelectedRemoteRepo :: B9 (Maybe RemoteRepo) getRemoteRepos :: B9 [RemoteRepo] getRepoCache :: B9 RepoCache cmd :: String -> B9 () instance Eq ProfilingEntry instance Show ProfilingEntry instance Functor B9 instance Applicative B9 instance Monad B9 instance MonadState BuildState B9 instance MonadIO B9 -- | Effectful functions executing shared image respository operations. See -- B9.Repository module B9.RepositoryIO -- | Find files which are in subDir and match glob in the -- repository cache. NOTE: This operates on the repository cache, but -- does not enforce a repository cache update. repoSearch :: FilePath -> FilePathGlob -> B9 [(Repository, [FilePath])] -- | Push a file from the cache to a remote repository pushToRepo :: RemoteRepo -> FilePath -> FilePath -> B9 () -- | Pull a file from a remote repository to cache pullFromRepo :: RemoteRepo -> FilePath -> FilePath -> B9 () -- | Push a file from the cache to a remote repository pullGlob :: FilePath -> FilePathGlob -> RemoteRepo -> B9 () data Repository Cache :: Repository Remote :: String -> Repository -- | Express a pattern for file paths, used when searching repositories. data FilePathGlob FileExtension :: String -> FilePathGlob instance Eq Repository instance Ord Repository instance Read Repository instance Show Repository -- | Effectful functions that create and convert disk image files. module B9.DiskImageBuilder -- | Create an image from an image source. The destination image must have -- a compatible image type and filesyste. The directory of the image MUST -- be present and the image file itself MUST NOT alredy exist. materializeImageSource :: ImageSource -> Image -> B9 () -- | Replace $... variables inside an ImageTarget substImageTarget :: [(String, String)] -> ImageTarget -> ImageTarget -- | Return all valid image types sorted by preference. preferredDestImageTypes :: ImageSource -> B9 [ImageType] preferredSourceImageTypes :: ImageDestination -> [ImageType] -- | Resolve an ImageSource to an Image. Note however that this -- source will may not exist as is the case for EmptyImage. resolveImageSource :: ImageSource -> B9 Image createDestinationImage :: Image -> ImageDestination -> B9 () -- | Resize an image, including the file system inside the image. resizeImage :: ImageResize -> Image -> B9 () -- | Import a disk image from some external source into the build directory -- if necessary convert the image. importImage :: Image -> Image -> B9 () -- | Export a disk image from the build directory; if necessary convert the -- image. exportImage :: Image -> Image -> B9 () -- | Export a disk image from the build directory; if necessary convert the -- image. exportAndRemoveImage :: Image -> Image -> B9 () -- | Convert an image in the build directory to another format and return -- the new image. convertImage :: Image -> Image -> B9 () -- | Publish an sharedImage made from an image and image meta data to the -- configured repository shareImage :: Image -> SharedImageName -> B9 SharedImage ensureAbsoluteImageDirExists :: Image -> IO Image -- | Publish the latest version of a shared image identified by name to the -- selected repository from the cache. pushSharedImageLatestVersion :: SharedImageName -> B9 () -- | Find shared images and the associated repos from two predicates. The -- result is the concatenated result of the sorted shared images -- satisfying imgPred. lookupSharedImages :: (Repository -> Bool) -> (SharedImage -> Bool) -> B9 [(Repository, SharedImage)] -- | Return a list of all existing sharedImages from cached repositories. getSharedImages :: B9 [(Repository, [SharedImage])] -- | Pull metadata files from all remote repositories. pullRemoteRepos :: B9 () -- | Pull the latest version of an image, either from the selected remote -- repo or from the repo that has the latest version. pullLatestImage :: SharedImageName -> B9 Bool -- | Implementation of an execution environment that uses "libvirt-lxc". module B9.LibVirtLXC runInEnvironment :: ExecEnv -> Script -> B9 Bool supportedImageTypes :: [ImageType] setDefaultConfig :: ConfigParser instance Read LXCGuestCapability instance Show LXCGuestCapability instance Read LibVirtLXCConfig instance Show LibVirtLXCConfig -- | Effectful functions to execute and build virtual machine images using -- an execution environment like e.g. libvirt-lxc. module B9.VmBuilder buildWithVm :: InstanceId -> [ImageTarget] -> FilePath -> VmScript -> B9 Bool -- | Mostly effectful functions to assemble artifacts. module B9.ArtifactGeneratorImpl -- | Run an artifact generator to produce the artifacts. assemble :: ArtifactGenerator -> B9 [AssembledArtifact] parseArtifactGenerator :: ArtifactGenerator -> CGParser () withArtifactSources :: [ArtifactSource] -> CGParser () -> CGParser () withBindings :: [(String, String)] -> CGParser () -> CGParser () addBindings :: [(String, String)] -> CGEnv -> CGEnv withXBindings :: [(String, [String])] -> CGParser () -> CGParser () eachBindingSetT :: ArtifactGenerator -> [String] -> [[String]] -> CGParser [[(String, String)]] eachBindingSet :: ArtifactGenerator -> [(String, [String])] -> CGParser [[(String, String)]] writeInstanceGenerator :: InstanceId -> ArtifactAssembly -> CGParser () -- | Monad for creating Instance generators. newtype CGParser a CGParser :: WriterT [InstanceGenerator CGEnv] (ReaderT CGEnv (Either CGError)) a -> CGParser a runCGParser :: CGParser a -> WriterT [InstanceGenerator CGEnv] (ReaderT CGEnv (Either CGError)) a data CGEnv CGEnv :: [(String, String)] -> [ArtifactSource] -> CGEnv agEnv :: CGEnv -> [(String, String)] agSources :: CGEnv -> [ArtifactSource] data InstanceGenerator e IG :: InstanceId -> e -> ArtifactAssembly -> InstanceGenerator e newtype CGError CGError :: String -> CGError cgError :: String -> CGParser a execCGParser :: CGParser () -> CGEnv -> Either CGError [InstanceGenerator CGEnv] execIGEnv :: InstanceGenerator CGEnv -> Either String (InstanceGenerator [SourceGenerator]) substAssembly :: [(String, String)] -> ArtifactAssembly -> ArtifactAssembly toSourceGen :: [(String, String)] -> ArtifactSource -> Either String [SourceGenerator] createAssembledArtifacts :: [InstanceGenerator [SourceGenerator]] -> B9 [AssembledArtifact] generateSources :: FilePath -> InstanceGenerator [SourceGenerator] -> B9 (InstanceGenerator FilePath) createTargets :: InstanceGenerator FilePath -> B9 AssembledArtifact generateUniqueIID :: InstanceId -> B9 InstanceId generateSourceTo :: FilePath -> SourceGenerator -> B9 () sgReadSourceFile :: [(String, String)] -> SourceFile -> B9 ByteString sgChangePerm :: FilePath -> SGPerm -> B9 () -- | Internal data type simplifying the rather complex source generation by -- bioling down ArtifactSources to a flat list of uniform -- SourceGenerators. data SourceGenerator SGConcat :: [(String, String)] -> SGSource -> SGPerm -> FilePath -> SourceGenerator data SGSource SGFiles :: [SourceFile] -> SGSource SGContent :: Content -> SGSource data SGType SGT :: SGType SGF :: SGType data SGPerm SGSetPerm :: (Int, Int, Int) -> SGPerm KeepPerm :: SGPerm sgGetFroms :: SourceGenerator -> [SourceFile] setSGPerm :: Int -> Int -> Int -> SourceGenerator -> Either String SourceGenerator setSGFromDirectory :: FilePath -> SourceGenerator -> SourceGenerator setSGToDirectory :: FilePath -> SourceGenerator -> SourceGenerator -- | Create the actual target, either just a mountpoint, or an ISO or VFAT -- image. createTarget :: InstanceId -> FilePath -> ArtifactAssembly -> B9 [ArtifactTarget] instance Typeable InstanceGenerator instance Typeable CGError instance Typeable SGType instance Typeable SGPerm instance Read CGEnv instance Show CGEnv instance Eq CGEnv instance Read e => Read (InstanceGenerator e) instance Show e => Show (InstanceGenerator e) instance Data e => Data (InstanceGenerator e) instance Eq e => Eq (InstanceGenerator e) instance Read CGError instance Show CGError instance Data CGError instance Eq CGError instance Error CGError instance Functor CGParser instance Applicative CGParser instance Monad CGParser instance MonadReader CGEnv CGParser instance MonadWriter [InstanceGenerator CGEnv] CGParser instance MonadError CGError CGParser instance Read SGSource instance Show SGSource instance Eq SGSource instance Read SGType instance Show SGType instance Data SGType instance Eq SGType instance Read SGPerm instance Show SGPerm instance Data SGPerm instance Eq SGPerm instance Read SourceGenerator instance Show SourceGenerator instance Eq SourceGenerator -- | Highest-level build functions and and B9-re-exports. module B9.Builder buildArtifacts :: ArtifactGenerator -> ConfigParser -> B9Config -> IO Bool -- | B9 is a library and build tool with primitive operations to run a -- build script inside a virtual machine and to create and convert -- virtual machine image files as well as related ISO and VFAT disk -- images for e.g. cloud-init configuration sources. -- -- This module re-exports the modules needed to build a tool around the -- library, e.g. see src/cli/Main.hs as an example. -- -- B9.ArtifactGenerator is the module containing the basic data -- structure used to describe a B9 build. module B9 -- | Merge existingConfig with the configuration from the main b9 -- config file. If the file does not exists, a new config file with the -- given configuration will be written. The return value is a parser for -- the config file. Returning the raw config file parser allows modules -- unkown to B9Config to add their own values to the shared config -- file. configure :: MonadIO m => Maybe SystemPath -> B9Config -> m ConfigParser -- | Return the cabal package version of the B9 library. b9_version :: Version