file-embed 0.0.8.1 → 0.0.8.2

raw patch · 3 files changed

+39/−1 lines, 3 filesPVP ok

version bump matches the API change (PVP)

API changes (from Hackage documentation)

Files

• ChangeLog.md +4/−0
• Data/FileEmbed.hs +34/−0
• file-embed.cabal +1/−1

@@ -1,3 +1,7 @@+## 0.0.8.2++* Improve inject documentation [#11](https://github.com/snoyberg/file-embed/issues/11)+ ## 0.0.8.1  Minor cleanup

@@ -23,6 +23,7 @@     , embedDir     , getDir       -- * Inject into an executable+      -- $inject #if MIN_VERSION_template_haskell(2,5,0)     , dummySpace     , dummySpaceWith@@ -182,6 +183,8 @@      in replicate (sizeLen - length s) '0' ++ s  #if MIN_VERSION_template_haskell(2,5,0)+-- | Allocate the given number of bytes in the generate executable. That space+-- can be filled up with the 'inject' and 'injectFile' functions. dummySpace :: Int -> Q Exp dummySpace = dummySpaceWith "MS" @@ -206,6 +209,9 @@     [| getInner (B.drop magicLen (unsafePerformIO (unsafePackAddressLen len $(return chars)))) |] #endif +-- | Inject some raw data inside a @ByteString@ containing empty, dummy space+-- (allocated with @dummySpace@). Typically, the original @ByteString@ is an+-- executable read from the filesystem. inject :: B.ByteString -- ^ bs to inject        -> B.ByteString -- ^ original BS containing dummy        -> Maybe B.ByteString -- ^ new BS, or Nothing if there is insufficient dummy space@@ -232,6 +238,9 @@             [] -> error $ "Data.FileEmbed (inject): Your dummy space has been corrupted. Size is: " ++ show sizeBS     after = B.drop size rest' +-- | Same as 'inject', but instead of performing the injecting in memory, read+-- the contents from the filesystem and write back to a different file on the+-- filesystem. injectFile :: B.ByteString -- ^ bs to inject            -> FilePath -- ^ template file            -> FilePath -- ^ output file@@ -251,3 +260,28 @@     case injectWith postfix inj src of         Nothing -> error "Insufficient dummy space"         Just dst -> B.writeFile dstFP dst++{- $inject++The inject system allows arbitrary content to be embedded inside a Haskell+executable, post compilation. Typically, file-embed allows you to read some+contents from the file system at compile time and embed them inside your+executable. Consider a case, instead, where you would want to embed these+contents after compilation. Two real-world examples are:++* You would like to embed a hash of the executable itself, for sanity checking in a network protocol. (Obviously the hash will change after you embed the hash.)++* You want to create a self-contained web server that has a set of content, but will need to update the content on machines that do not have access to GHC.++The typical workflow use:++* Use 'dummySpace' or 'dummySpaceWith' to create some empty space in your executable++* Use 'injectFile' or 'injectFileWith' from a separate utility to modify that executable to have the updated content.++The reason for the @With@-variant of the functions is for cases where you wish+to inject multiple different kinds of content, and therefore need control over+the magic key. If you know for certain that there will only be one dummy space+available, you can use the non-@With@ variants.++-}

@@ -1,5 +1,5 @@ name:            file-embed-version:         0.0.8.1+version:         0.0.8.2 license:         BSD3 license-file:    LICENSE author:          Michael Snoyman <michael@snoyman.com>