CHANGELOG.md 19.3 KB
Newer Older
1
2
# Hoppy Changelog

Bryan Gardiner's avatar
Bryan Gardiner committed
3
4
## Unreleased - 0.8.1

Bryan Gardiner's avatar
Bryan Gardiner committed
5
6
- runtime: Bump to allow Cabal-3.4.

Bryan Gardiner's avatar
Bryan Gardiner committed
7
## *-0.8.0 (2021-02-06)
8

9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
- [API change] Hoppy generators are now meant to be invoked as libraries rather
  than as executables, as part of the normal build process for a set of
  bindings.  Cabal doesn't properly support `custom-setup` depending on
  executables from other packages (see the Cabal issue linked below); invoking
  the dependency's code as a library is the recommended route instead.

  See the subsection below this list for instructions on how to update your
  code.

  Qtah has migrated to calling its generator this way too; this is the way
  forward, but the current interface for calling the generator as a library is
  still pretending it's a command line, and could use some cleanup.

  See "Support for `setup-tool-depends`" here:
  https://github.com/haskell/cabal/issues/4648

25
26
27
28
29
30
- [API change] CustomCompiler now has an additional `ccHeaderSearchPath` field.
  It can default to an empty list.  This is to support the new
  `prependIncludePath` method added to the `Compiler` typeclass.  The
  `ccCompile` field has an extra argument as well: the compiler being invoked,
  so that it has access to this search path.

31
32
33
34
35
- [API change] The enum numeric type info types and functions have moved from
  `Foreign.Hoppy.Generator.Hook` to `Foreign.Hoppy.Generator.Spec.Computed`.
  Unless you're explicitly using `NumericTypeInfo`, this probably doesn't affect
  you.

36
- Updated the example bindings to support Cabal Nix-style builds with v2-build.
37
38
  Also Hoppy tests are now runnable via `cabal v2-test`.  To support this, both
  the example and the tests now call their generators as a library.
39

40
41
42
43
44
- Added support for caching the results of enum evaluation, when it takes place
  during generation of a C++ gateway package, so that generation of the Haskell
  package can reuse the result and not have to run C++ compilation a second time
  (issue #41, bug #45).

45
46
47
  Bindings using `Hoppy.Foreign.Runtime.Setup` now cache enum results
  automatically.

48
49
50
51
52
- Hoppy's enum evaluation machinery now includes the sources directory of a C++
  gateway package on the header search path automatically during its
  compilation, so that bindings can reference enums declared in the C++ gateway
  package itself (issue #45).

53
54
55
56
- The generator now has additional `--clean-cpp` and `--clean-hs` options.
  These both take an argument, like `--gen-cpp` and `--gen-hs`, but remove
  generated files rather than creating them.

57
58
59
60
- The minimum Cabal version for all packages has been bumped to 1.24, as
  required for `custom-setup` stanzas.  This was already a requirement, but the
  `cabal-version` was out of date and said 1.10.

61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
### Converting your generators into libraries

Previously, generator packages needed to contain an executable, and that
executable was recommended to use a main function of:

    import Foreign.Hoppy.Generator.Main (defaultMain)
    import Foreign.Hoppy.Generator.Spec (Interface, interface)

    interfaceResult :: Either String Interface
    interfaceResult = interface ...

    main = defaultMain interfaceResult

The C++ and Haskell gateway packages would then have a custom Setup.hs that set
`generatorExecutableName` to the name of this executable within `ProjectConfig`.

Now, the definitions of the generator can stay the same, but the interface
definitions need to be moved over to the library component of the generator, and
the `interfaceResult` needs to be exported from an exposed module.  The
executable can be kept if desired, for testing the generator out from the
command line, though this is not a requirement.  It only needs to contain the
`main` definition.

The dummy module included in the example generator's library is no longer
needed, since the library contains actual code now.

The fields in `ProjectConfig` have changed as well, so to update the two gateway
packages, remove the `generatorExecutableName` and `interfaceName` fields and
add an `interfaceResult` field whose value is the result object exported from
the library.  The gateway packages should now have a regular dependency on the
generator package from their `setup-depends` section.  No dependency is
necessary on the generator from the either of the gateway package's libraries
anymore.  The gateway packages should still depend on `hoppy-runtime`, and the
Haskell gateway package should still depend on the C++ gateway package.

If in doubt, see the example bindings.

98
## hoppy-generator-0.7.1, hoppy-std-0.7.1 (2020-03-30)
99

100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
- Added support for GHC 8.8.* and 8.10.1 (issue #44).  Updates for the
  [MonadFail](https://prime.haskell.org/wiki/Libraries/Proposals/MonadFail)
  proposal were needed, as well as some other updates for newly-detected
  redundant imports.  Cabal up to 3.2 is now supported.

  As part of these changes, many non-PVP-compliant imports from hoppy-std to
  Foreign.Hoppy.Generator.Spec were fixed.

  I also had to tweak the test coverage of the Nix builds: haskell-src needs its
  dependency versions ignored when building with ghc-8.6.4, and it won't build
  without further work against ghc-8.4.4, so I've removed ghc-8.4.4 from the
  automatic Nix tests.  (I'm currently building these against the Nixpkgs
  unstable channel to verify all these, since I'm experiencing issues building
  haskell-src against various GHCs on the nixos-19.09 channel.)

115
## *-0.7.0 (2019-12-23)
116

117
118
119
120
121
122
- [API change] There is a new `Scoped` boolean data type to indicate whether an
  enum is a scoped enum (e.g. `enum class`) or an unscoped enum (the old
  `enum`).  This type is now expected as an argument to `makeAutoEnum` rather
  than a raw boolean.  It turns out to be necessary to store this on enums
  themslves, so it makes sense to improve the `makeAutoEnum` parameter at the
  same time.
123

124
125
126
- Fix for autodetection of scoped enum values (issue #43).  For now,
  autodetection for scoped enums only works with C++11 and up.

127
128
## *-0.6.0 (2019-09-29)

Bryan Gardiner's avatar
Bryan Gardiner committed
129
130
131
132
133
134
135
136
137
138
139
This release is a significant refactoring of Hoppy, featuring many new features
and changes to its API.

- Compatibility with GHC 8.6, Cabal 2.4.

- [API change] C++ data types have been generalized, and you can now define your
  own kinds of entities to be exported, in parallel with enums, objects,
  variables, functions, etc.

  The core of this is the support is the `Exportable` typeclass, which defines
  the entry points that Hoppy will call to generate support code necessary on
140
141
142
  either side of a binding, if needed.  Rather than `Export` having a number of
  fixed data constructors, it's now an existential data type that wraps an
  `Exportable`, and can be created with the `toExport` function.
Bryan Gardiner's avatar
Bryan Gardiner committed
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217

- Marshalling of values between C++ and Haskell has also been generalized and is
  now extensible to your own types or specific arguments, as you see fit
  (issue #9).

  The main entry point here is the `ConversionSpec` data type, which specifies
  C++ and Haskell types and the code generators necessary to convert values
  between them.  A `ConversionSpec` can be lifted to a `Type` with the function
  `manualT`, and various existing type functions (`intT`, `enumT`, etc.) are
  wrappers around this function.

  All of the built-in number types are now implemented via this mechanism, and
  you can create your own with `makeNumericType`.  The `Type` data type has been
  reduced to a handful of primitive types, and all of the nonessentials have
  been split out to use the new generic support.  This doesn't affect the use of
  the `typeT` functions.

  Classes and `objT` still remain to be unified with this new way.  For now,
  class conversions are still handled via `ClassConversion`.

- [API change] Enum support has been improved in many ways.

  First and most importantly, Hoppy can now compute the ordinal values for enum
  entries itself, by building a sample program with a provided compiler
  (issue #17).  Binding authors no longer need to determine these values, hard
  code them into their bindings, and hope they don't change.  These new-style
  enums can be created with `makeAutoEnum`.  Enums can still be created the old
  way, for example if it's not convenient to call a C++ compiler.  By default,
  g++ is assumed to be present and any manually-specified enum details will be
  verified by running the compiler.  Compilation can be disabled with
  `interfaceSetNoCompiler`.

  Secondly, as part of `makeAutoEnum`, enum entry names are easier to specify.
  You now just specify the C++ name of the entry, rather than splitting them up
  into words.

  Thirdly, previously Hoppy assumed that enums were backed by a C++ int, which
  is bad because this type can have both the wrong width, and the wrong
  signedness (issue #30).  As part of enum autodetection, this is computed
  automatically now.  For old-style enums, a data type can be provided manually.

  Fourthly, Hoppy used to generate `Bounded` and `Enum` instances for C++ enums
  in Haskell, and it no longer does (issue #7); instead, it generates an
  instance of a new typeclass `CppEnum`.  The instances generated were incorrect
  when the enum's numeric values weren't all sequential integers.  The instance
  generated for `Bounded` incorrectly used the first and last entries in the
  list provided to `makeEnum` (I suppose we could instead take the lowest and
  highest numeric value though).  For `Enum`, the instances used the default
  `succ` and `pred` instances of adding and subtracting one, which isn't
  guaranteed to work.  Also, both of these only work with `Int` (see the
  previous paragraph).  The new `CppEnum` typeclass only supports the bare
  minimum for now: `toCppEnum` and `fromCppEnum`.

  Fifthly, multiple enum entries having the same ordinal value is now supported.

  Sixthly, enums can now optionally represent values that aren't included in the
  binding's definition (issue #4).  This supports the case where a new enum
  value has been added by the C++ library but it hasn't been added to the
  bindings yet.  This is a choice for each enum: either the enum doesn't support
  unknown values, and Haskell will `error` if one is seen, or it will have an
  additional "unknown" data constructor that will have to be pattern-matched
  against, but `toCppEnum` will never error out.

  Seventhly, Haskell bindings for enums now get `Bits` instances.  This is on by
  default and can be disabled on a per-enum basis.

- [API change] Bitspaces are now removed.

  In case you didn't see this coming after the above: bitspaces were a hack in
  order to support QFlags in Qtah, and all of the logic necessary to support
  this in a more general fashion within Qtah itself has been added via the above
  points, so bitspaces are gone from Hoppy.

- [API change] Function parameters can now be named (issue #12).

218
219
220
  Names can now be attached to function parameters.  These names are used as
  type variable names and Haddock documentation generated code, so that binding
  users can see these names rather than just arg1, arg2, and so on, as before.
Bryan Gardiner's avatar
Bryan Gardiner committed
221
222
223
224
225
226
227
228

  Unfortunately, this causes some unpleasant API breakage.

  Parameter lists to `makeFn`, `mkMethod`, etc. are now generic.  They can
  either be `[Type]` as before, or `(~:)` can be used to attach names to types
  to give `[Parameter]`.  The breakage is that the empty list is now ambiguously
  typed, so a new `np = [] :: [Parameter]` value should be used instead.

229
230
231
232
233
234
235
236
237
238
239
- Initial support has been added for exported names to be overridable on a
  per-language basis, with data types in `Foreign.Hoppy.Generator.Overrides`.
  This is used in conjunction with `makeAutoEnum` enum entries, where this is
  the mechanism to provide a Haskell name different than the C++ name (see
  `enumAddEntryNameOverrides`).

  For all other entities (functions, variables, classes, etc.), you can just
  give the entity a different external name than its C++ name, and only one
  foreign language is supported, so this isn't necessary now, but these
  overrides may be more tightly integrated with `ExtName`s in the future.

Bryan Gardiner's avatar
Bryan Gardiner committed
240
241
242
243
- Generator binaries have new `--dump-ext-names` and `--dump-enums` options for
  displaying information for debugging purposes, suhc as enum information
  determined from the C++ compiler.

Bryan Gardiner's avatar
Bryan Gardiner committed
244
245
- `wchar_t` and `wstring` have been added to the standard library bindings.

Bryan Gardiner's avatar
Bryan Gardiner committed
246
247
248
249
- The Nix expressions, which had long been languishing, have been brought up to
  date, and now make use of Nix overlays.  The example now includes Nix
  expressions.

250
251
## hoppy-generator-0.5.2 (2018-09-01)

252
- Generated bindings now require GHC 7.10 or newer (released Apr 2015), and no
253
254
255
256
  longer use the CPP extension (issue #35).

- Generated bindings now have the MonoLocalBinds extension enabled to address
  the -Wsimplifiable-class-constraints warning in GHC 8.2+ (issue #36).
257

258
259
260
261
## hoppy-runtime-0.5.1 (2018-08-25)

- Bump to support Cabal 2.2.

262
263
## hoppy-generator-0.5.1 (2018-08-06)

264
265
266
267
- Added the ForeignFunctionInterface extension explicitly to generated bindings,
  because of a report at https://gitlab.com/khumba/qtah/issues/30 that it isn't
  always enabled by default.

268
269
270
271
- Added compatibility with GHC 8.4 with respect to the Semigroup Monoid Proposal
  (https://prime.haskell.org/wiki/Libraries/Proposals/SemigroupMonoid), thanks
  @locallycompact.

272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
## *-0.5.0 (2018-06-05)

Big thanks to Masahiro Sakai for his contributions to this release, which
include all of the following.

- Fixed exception handlers declared on functions incorrectly being sorted, when
  the order should be taken as is, because it affects the order in which 'catch'
  blocks appear in generated C++ code (issue #27).

- Fixed Haskell exception upcasting code, which caused build errors for
  generated code (MR !3).

- Fixed building of the example program on macOS (MR !4).

- Fixed NUL character handling in the conversions between Haskell's `String` and
  C++'s `std::string`, each of which can hold NUL characters (MR !10).

289
290
291
292
- Fixed the bindings for `std::set` to account for the fact that the C++
  standard allows `set::iterator` and `set::const_iterator` to be different
  types, and added bindings for `std::unordered_map` and `std::unordered_set`
  (MR !9).
293
294
295

- Changes to support 'cabal new-build' and 'new-repl' (MRs !7, !8).

Bryan Gardiner's avatar
Bryan Gardiner committed
296
297
## *-0.4.0 (2018-01-27)

298
299
300
301
302
303
304
305
306
307
- Fixed a const-safety bug with methods.  The C++ generator was always using
  non-const this pointers when writing gateway functions for methods, even when
  a method was marked as const.  This meant that it was possible to use
  "mkConstMethod" on a non-const method and pass in const objects (which would
  be implicitly cast to non-const).

  This may cause breakage when building your bindings, but only does so if you
  have mistakenly labelled non-const methods as const.  std::string::at() was
  affected by this and has been corrected.

308
309
- Fixed some incorrect typeclass names in the user's guide.

310
311
## hoppy-generator-0.3.4, hoppy-runtime-0.3.2 (2017-12-30)

312
313
314
315
316
- Added a means for using a custom `shared_ptr` implementation via
  `interfaceSetSharedPtr`.  Hoppy normally uses `std::shared_ptr` in its
  implementation of callbacks, but this isn't always available (e.g. with older
  compilers).

Bryan Gardiner's avatar
Bryan Gardiner committed
317
318
- Added support for Cabal 2.0.

319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
- Bug fixes for bitspaces:

  - Negative numeric values are now supported, as they are for enums.

  - There was a duplicate typeclass instance being generated when a bitspace's
    Haskell-side Haskell and C numeric types were the same.

- Bug fixes for exception handling:

  - The generated Haskell code for functions that throw and also need
    Haskell-side return value conversion wouldn't compile (the
    internalHandleExceptions call was placed at the wrong point).

  - There was a null pointer dereference in C++ coming back from throwing
    callbacks that return refT or objT.

  - Generated code used a mix of prepended and appended exception arguments for
    callbacks (everywhere prepended except for callbackToTFn).  Now callbacks
    consistently append those arguments, as is done for throwing C++ functions.

339
340
## hoppy-generator-0.3.3, hoppy-runtime-0.3.1, hoppy-docs-0.3.2 (2017-06-08)

341
342
343
344
- Added default Setup.hs implementations for gateway packages, to encapsulate
  the magic that is needed to make bindings work (issue #13).  See
  Foreign.Hoppy.Setup in hoppy-runtime and the example/ directory that uses it.

345
346
347
348
349
- Callback functors are now default constructable, so that callbacks in C++ can
  be optional.  Like std::shared_ptr, casting to bool determines whether the
  callback is populated and may be called.  It is not valid to invoke a
  default-constructed callback.

350
351
352
353
354
355
356
357
## hoppy-generator-0.3.2, hoppy-docs-0.3.1 (2017-02-26)

- Added a proper tutorial to the user's guide, and improved various bits of
  documentation in the generator.

- Added a default `main` implementation to the generator for bindings to use,
  instead of having to write their own.

358
359
## hoppy-generator-0.3.1 (2017-02-18)

360
361
- Fixed an infinite loop in the C++ generator and a mistake in the Haskell
  generator when using `toGcT . objT` in a callback argument (issue #22).
362

363
364
365
- Dependency bump to support directory-1.3 in GHC 8.0.2.

## *-0.3.0 (2016-12-16)
366

367
368
369
- [API change] Added support for customizing the prefixes of class methods and
  constructors, as well as enum and bitspace values, so that we can simplify the
  Qtah generator and make using Qtah's enums and bitspaces less painful on the
370
371
372
373
374
375
  fingers (https://gitlab.com/khumba/qtah/issues/10).

  Consequently, Haskell name generation functions are now monadic, since
  generated Haskell modules now import each other qualified (but this simplifies
  the Haskell generator some since cross-module dependencies are now imported
  implicitly).
376

377
378
379
380
381
- [API change] Merged constructors, methods, and properties into a single list
  when declaring classes, and simplifying down from the previous
  "makeClass ... [ctors] $ [methods] ++ mkProps [props]" to
  "makeClass ... [ctors..., methods..., props...]".

382
383
384
385
386
387
388
- [API change] Split class convertibility into convertibility in each direction
  (issue #15).  Now classSetConversionToGc and classSetConversionToHeap are not
  special; they're just implemented as a regular class conversion that only
  supports decoding.  This allows container classes whose conversions use
  'encode' and 'decode' to convert their elements, to contain convert-to-GC/heap
  objects as well now.

389
390
- Added support for class member variables.

391
392
- Added support for function pointers (issue #14).

393
394
395
- Added support for using C++ exceptions in Haskell (issue #10).  Exceptions are
  automatically passed between C++ and Haskell in gateway code that is specified
  to support them.  The main Haskell interface is via catchCpp and throwCpp.
396

397
398
399
- Added addenda to modules, to provide a place to inject custom code at the
  module level (issue #11).

400
401
402
- Added the ability to enable custom Haskell language extensions for generated
  modules.

403
## *-0.2.1 (2016-10-01)
Bryan Gardiner's avatar
Bryan Gardiner committed
404
405
406

- Bumped the upper version of the base dependency to 5; base releases often.

407
## *-0.2.0 (2016-06-29)
408
409
410

- Added foreign garbage collector support (issue #5).

411
412
413
414
415
416
417
- Classes can now be set so that returning an `objT cls` is equivalent to
  returning `objToHeapT cls` or `toGcT (objT cls)`.

- Bitspace parameters to C++ functions now accept any type in the bitspace's
  typeclass, rather than just the bitspace type (so integers can be passed
  directly).

418
419
420
- Major API change for specifying C++ types (issue #9).  A set of bindings
  replaces the data constructors of `Type`.  This is to make it easier to create
  new types in the future.
421
422

- `intT`, `floatT`, and `doubleT` now use `Int`, `Float`, and `Double` as their
423
424
  Haskell types, rather than the awkward `CInt`, `CFloat`, and `CDouble`
  (issue #3).
425
426
427

- Small fixes to the user guide and unit tests.

428
## *-0.1.0 (2016-02-08)
429
430

- Initial release.