spago bundle instructions

CHANGELOG.md

@@ -1,5 +1,7 @@
 # Unreleased
 
+# v4.5.0 2024-12-02
+
 - `spago@next` build system. Reorganized packages.
 
 # v4.4.0 2024-10-15

README.md

@@ -258,7 +258,7 @@ programs which use code generated by __protobuf__. Refer to these
 for further examples of how to use the generated code.
 
 1. The `protoc`
-   [compiler plugin](https://github.com/xc-jp/purescript-protobuf/blob/master/plugin/src/ProtocPlugin/Main.purs).
+   [compiler plugin](https://github.com/xc-jp/purescript-protobuf/blob/master/plugin/src/Main.purs).
    The code generator imports generated code. This program writes itself.
 2. The
    [unit test suite](https://github.com/xc-jp/purescript-protobuf/blob/master/library/test/Main.purs)

bin/protoc-gen-purescript

@@ -1,2 +1,2 @@
 #!/usr/bin/env bash
-node --input-type=module -e "import {main} from './plugin/output/ProtocPlugin.Main/index.js'; main();"
+node --input-type=module -e "import {main} from './plugin/output/Main/index.js'; main();"

conformance/README.md

@@ -2,20 +2,38 @@
 
 ## Running the conformance test
 
+### Running with Nix
+
 From the top directory of this repo,
 
-```console
+```shell
 nix run .#conformance
 ```
-or
-```console
+
+### Running from output/
+
+```shell
 cd conformance
+```
+```shell
 spago build
 ```
-```console
+```shell
 conformance_test_runner --enforce_recommended bin/conformance-purescript
 ```
 
+### Running from bundled executable
+
+```shell
+cd conformance
+```
+```shell
+spago bundle --platform=node --minify --bundle-type app --outfile conformance.mjs
+```
+```shell
+conformance_test_runner --enforce_recommended ./conformance.mjs
+```
+
 ## About the conformance test runner
 
 [Conformance README](https://github.com/protocolbuffers/protobuf/tree/master/conformance)
@@ -27,9 +45,9 @@ The derivations in `nix/protobuf.nix` will build `protoc` and the
 
 To generate the conformance `.purs` in the dev environment:
 
-```console
+```shell
 protoc --purescript_out=./conformance/src/generated --proto_path=$(nix path-info .#protobuf)/conformance $(nix path-info .#protobuf)/conformance/conformance.proto
 ```
-```console
+```shell
 protoc --purescript_out=./conformance/src/generated --proto_path=$(nix path-info .#protobuf)/src $(nix path-info .#protobuf)/src/google/protobuf/test_messages_proto3.proto
 ```

flake.nix

@@ -51,10 +51,6 @@
               buildPhase = ''
                 spago build --purs-args '${prev.purescript-protobuf-library.src}/src/**/*.purs'
                 '';
-                # The bundled minified output is CommonJS, so we need to change the run script to run node with CommonJS?
-                # spago build --purs-args '${prev.purescript-protobuf-library.src}/**/*.purs'
-                # purs-backend-es bundle-app --no-build --platform node --minify --output-dir output --main ProtocPlugin.Main
-                # spago bundle --offline --pure --platform node --bundle-type app --minify --module ProtocPlugin.Main --purs-args '${prev.purescript-protobuf-library.src}/**/*.purs'
               installPhase = "mkdir $out; cp -r output/* $out/";
             };
           })
@@ -71,7 +67,7 @@
           })
           (prev: final: {
               protoc-gen-purescript = prev.writeScriptBin "protoc-gen-purescript" ''
-                ${prev.nodejs}/bin/node --input-type=module -e "import {main} from '${final.purescript-protobuf-plugin}/ProtocPlugin.Main/index.js'; main();"
+                ${prev.nodejs}/bin/node --input-type=module -e "import {main} from '${final.purescript-protobuf-plugin}/Main/index.js'; main();"
                 '';
               conformance-purescript = prev.writeScriptBin "conformance-purescript" ''
                 #!/usr/bin/env bash

plugin/README.md

@@ -1,12 +1,57 @@
 
 # PureScript plugin for Protoc
 
-Build:
+## Build
 
-```
+```shell
 spago build
 ```
 
+## Bundle and Run
+
+```shell
+spago bundle --platform node --minify --bundle-type app --outfile protoc-gen-purescript.mjs
+```
+
+```shell
+protoc --plugin=protoc-gen-purescript=./protoc-gen-purescript.mjs --purescript_out=. google/protobuf/timestamp.proto
+```
+
+## Unit Tests
+
+To test purescript-protobuf, run `nix develop` from the top level directory
+of the repo, then:
+
+```shell
+protoc --purescript_out=./plugin/test/Test/generated ./plugin/test/*.proto
+```
+
+Or, for the bundled plugin, not the Nix store:
+
+```shell
+protoc --plugin=protoc-gen-purescript=./protoc-gen-purescript.mjs --purescript_out=./test/Test/generated --proto_path ./test ./test/*.proto
+```
+
+then
+
+```shell
+spago test
+```
+
+## Benchmarks
+
+To run the benchmarks, run `nix develop` from the top level directory, then:
+
+```console
+cd plugin
+```
+```console
+spago test --main Test.Bench
+```
+
+
+## Development
+
 The funny thing about writing a `protoc` compiler plugin codec is that it
 bootstraps itself. We just have to write enough of the compiler plugin codec
 that it can handle the `plugin.proto` and `descriptor.proto` files, and
@@ -17,7 +62,7 @@ Then we can delete the hand-written code and generate code to replace it
 with this command.
 
 ```shell
-protoc --purescript_out=./plugin/src/ProtocPlugin google/protobuf/compiler/plugin.proto
+protoc --plugin=protoc-gen-purescript=./protoc-gen-purescript.mjs --purescript_out=./src google/protobuf/compiler/plugin.proto
 ```
 
 See

plugin/src/ProtocPlugin/Main.purs → plugin/src/Main.purs

@@ -1,7 +1,7 @@
--- | Entry point for the code-generating executable `protoc` plugin. See the
--- | package README for instructions on how to run the code generator.
+-- | Entry point for the code-generating executable plugin `protoc-gen-purescript`.
+-- | See the package README for instructions on how to run the code generator.
 
-module ProtocPlugin.Main (main) where
+module Main (main) where
 
 import Prelude
 

plugin/test/README.md

@@ -1,37 +1 @@
 # Unit Tests
-
-`unittest_proto3_optional.proto` is copied from
-`$(dirname $(which protoc))/../src/google/protobuf/unittest_proto3_optional.proto`
-
-To test purescript-protobuf, run `nix develop` from the top level directory
-of the repo, then:
-
-```console
-protoc --purescript_out=./plugin/test/Test/generated ./plugin/test/*.proto
-```
-or, for the plugin from src tree, not the Nix store,
-``console
-protoc --plugin=bin/protoc-gen-purescript --purescript_out=./plugin/test/Test/generated ./plugin/test/*.proto
-```
-then
-```console
-cd plugin
-```
-```console
-spago build
-```
-```console
-spago test
-```
-
-# Benchmarks
-
-To run the benchmarks, run `nix develop` from the top level directory, then:
-
-```console
-cd plugin
-```
-```console
-spago test --main Test.Bench
-```
-

plugin/test/Test/generated/msg1.Pack.purs

@@ -1,4 +1,4 @@
--- | Generated by __protobuf__ from file `plugin/test/msg1.proto`
+-- | Generated by __protobuf__ from file `msg1.proto`
 module Pack.Msg1
 ( Msg1(..), Msg1Row, Msg1R, parseMsg1, putMsg1, defaultMsg1, mkMsg1, mergeMsg1
 , Msg1_E1(..)

plugin/test/Test/generated/msg2.Pack.purs

@@ -1,4 +1,4 @@
--- | Generated by __protobuf__ from file `plugin/test/msg2.proto`
+-- | Generated by __protobuf__ from file `msg2.proto`
 module Pack.Msg2
 ( Msg2(..), Msg2Row, Msg2R, parseMsg2, putMsg2, defaultMsg2, mkMsg2, mergeMsg2
 , Msg2_E1(..)

plugin/test/Test/generated/msg3.Pack3.purs

@@ -1,4 +1,4 @@
--- | Generated by __protobuf__ from file `plugin/test/msg3.proto`
+-- | Generated by __protobuf__ from file `msg3.proto`
 module Pack3.Msg3
 ( Msg3(..), Msg3Row, Msg3R, parseMsg3, putMsg3, defaultMsg3, mkMsg3, mergeMsg3
 , Msg3_Msg4(..), Msg3_Msg4Row, Msg3_Msg4R, parseMsg3_Msg4, putMsg3_Msg4, defaultMsg3_Msg4, mkMsg3_Msg4, mergeMsg3_Msg4

plugin/test/Test/generated/msg4.Pack4.purs

@@ -1,4 +1,4 @@
--- | Generated by __protobuf__ from file `plugin/test/msg4.proto`
+-- | Generated by __protobuf__ from file `msg4.proto`
 module Pack4.Msg4
 ( Msg2(..), Msg2Row, Msg2R, parseMsg2, putMsg2, defaultMsg2, mkMsg2, mergeMsg2
 , Msg1(..), Msg1Row, Msg1R, parseMsg1, putMsg1, defaultMsg1, mkMsg1, mergeMsg1

plugin/test/Test/generated/msg5.Pack5.purs

@@ -1,4 +1,4 @@
--- | Generated by __protobuf__ from file `plugin/test/msg5.proto`
+-- | Generated by __protobuf__ from file `msg5.proto`
 module Pack5.Msg5
 ( Msg1(..), Msg1Row, Msg1R, parseMsg1, putMsg1, defaultMsg1, mkMsg1, mergeMsg1, Msg1_Sum1(..)
 , Msg2(..), Msg2Row, Msg2R, parseMsg2, putMsg2, defaultMsg2, mkMsg2, mergeMsg2, Msg2_Sum1(..)

plugin/test/Test/generated/msg5_1.Pack5.purs

@@ -1,4 +1,4 @@
--- | Generated by __protobuf__ from file `plugin/test/msg5_1.proto`
+-- | Generated by __protobuf__ from file `msg5_1.proto`
 module Pack5.Msg51
 ( Msg2(..), Msg2Row, Msg2R, parseMsg2, putMsg2, defaultMsg2, mkMsg2, mergeMsg2
 )

plugin/test/Test/generated/msg6.Pack6.purs

@@ -1,4 +1,4 @@
--- | Generated by __protobuf__ from file `plugin/test/msg6.proto`
+-- | Generated by __protobuf__ from file `msg6.proto`
 module Pack6.Msg6
 ( Msg6(..), Msg6Row, Msg6R, parseMsg6, putMsg6, defaultMsg6, mkMsg6, mergeMsg6
 )

plugin/test/Test/generated/msg7.Pack7.purs

@@ -1,4 +1,4 @@
--- | Generated by __protobuf__ from file `plugin/test/msg7.proto`
+-- | Generated by __protobuf__ from file `msg7.proto`
 module Pack7.Msg7
 ( Msg7(..), Msg7Row, Msg7R, parseMsg7, putMsg7, defaultMsg7, mkMsg7, mergeMsg7
 )

plugin/test/msg3.proto

@@ -2,8 +2,8 @@ syntax = "proto3";
 
 package pack3;
 
-import "plugin/test/msg1.proto";
-import "plugin/test/msg2.proto";
+import "msg1.proto";
+import "msg2.proto";
 
 message msg3 {
   repeated pack.msg1 f1 = 1;

plugin/test/msg5_1.proto

@@ -2,7 +2,7 @@ syntax = "proto3";
 
 package pack5;
 
-import "plugin/test/msg5.proto";
+import "msg5.proto";
 
 message Msg2 {
   Msg1 f1 = 1;

plugin/test/msg6.proto

@@ -2,6 +2,9 @@ syntax = "proto3";
 
 package pack6;
 
+// `unittest_proto3_optional.proto` is copied from
+// `$(dirname $(which protoc))/../src/google/protobuf/unittest_proto3_optional.proto`
+
 // import "google/protobuf/unittest_proto3_optional.proto";
 
 message Msg6 {