cli: add documentation on create-{exe,obj}

lib/cli/src/cli.rs

@@ -49,13 +49,46 @@ enum WasmerCLIOptions {
     Compile(Compile),
 
     /// Compile a WebAssembly binary into a native executable
+    ///
+    /// To use, you need to set the `WASMER_DIR` environment variable
+    /// to the location of your Wasmer installation. This will probably be `~/.wasmer`. It
+    /// should include a `lib`, `include` and `bin` subdirectories. To create an executable
+    /// you will need `libwasmer`, so by setting `WASMER_DIR` the CLI knows where to look for
+    /// header files and libraries.
+    ///
+    /// Example usage:
+    ///
+    /// ```text
+    /// $ # in two lines:
+    /// $ export WASMER_DIR=/home/user/.wasmer/
+    /// $ wasmer create-exe qjs.wasm -o qjs.exe # or in one line:
+    /// $ WASMER_DIR=/home/user/.wasmer/ wasmer create-exe qjs.wasm -o qjs.exe
+    /// $ file qjs.exe
+    /// qjs.exe: ELF 64-bit LSB pie executable, x86-64 ...
+    /// ```
     #[cfg(any(feature = "static-artifact-create", feature = "wasmer-artifact-create"))]
-    #[structopt(name = "create-exe")]
+    #[structopt(name = "create-exe", verbatim_doc_comment)]
     CreateExe(CreateExe),
 
     /// Compile a WebAssembly binary into an object file
+    ///
+    /// To use, you need to set the `WASMER_DIR` environment variable to the location of your
+    /// Wasmer installation. This will probably be `~/.wasmer`. It should include a `lib`,
+    /// `include` and `bin` subdirectories. To create an object you will need `libwasmer`, so by
+    /// setting `WASMER_DIR` the CLI knows where to look for header files and libraries.
+    ///
+    /// Example usage:
+    ///
+    /// ```text
+    /// $ # in two lines:
+    /// $ export WASMER_DIR=/home/user/.wasmer/
+    /// $ wasmer create-obj qjs.wasm --object-format symbols -o qjs.obj # or in one line:
+    /// $ WASMER_DIR=/home/user/.wasmer/ wasmer create-exe qjs.wasm --object-format symbols -o qjs.obj
+    /// $ file qjs.obj
+    /// qjs.obj: ELF 64-bit LSB relocatable, x86-64 ...
+    /// ```
     #[cfg(feature = "static-artifact-create")]
-    #[structopt(name = "create-obj")]
+    #[structopt(name = "create-obj", verbatim_doc_comment)]
     CreateObj(CreateObj),
 
     /// Get various configuration information needed

lib/cli/src/commands/create_exe.rs

@@ -34,7 +34,12 @@ pub struct CreateExe {
     target_triple: Option<Triple>,
 
     /// Object format options
-    #[structopt(name = "OBJECT_FORMAT", long = "object-format")]
+    ///
+    /// This flag accepts two options: `symbols` or `serialized`.
+    /// - (default) `symbols` creates an
+    /// executable where all functions and metadata of the module are regular object symbols
+    /// - `serialized` creates an executable where the module is zero-copy serialized as raw data
+    #[structopt(name = "OBJECT_FORMAT", long = "object-format", verbatim_doc_comment)]
     object_format: Option<ObjectFormat>,
     #[structopt(short = "m", multiple = true, number_of_values = 1)]
     cpu_features: Vec<CpuFeature>,

lib/cli/src/commands/create_obj.rs

@@ -31,7 +31,11 @@ pub struct CreateObj {
     target_triple: Option<Triple>,
 
     /// Object format options
-    #[structopt(name = "OBJECT_FORMAT", long = "object-format")]
+    ///
+    /// This flag accepts two options: `symbols` or `serialized`.
+    /// - (default) `symbols` creates an object where all functions and metadata of the module are regular object symbols
+    /// - `serialized` creates an object where the module is zero-copy serialized as raw data
+    #[structopt(name = "OBJECT_FORMAT", long = "object-format", verbatim_doc_comment)]
     object_format: Option<ObjectFormat>,
 
     #[structopt(short = "m", multiple = true, number_of_values = 1)]
@@ -92,35 +96,15 @@ impl CreateObj {
                 let tunables = store.tunables();
                 let data: Vec<u8> = fs::read(wasm_module_path)?;
                 let prefixer: Option<Box<dyn Fn(&[u8]) -> String + Send>> = None;
-                let (module_info, obj, metadata_length, symbol_registry) =
+                let (_module_info, obj, _metadata_length, _symbol_registry) =
                     Artifact::generate_object(
                         compiler, &data, prefixer, &target, tunables, features,
                     )?;
 
-                let header_file_src = crate::c_gen::staticlib_header::generate_header_file(
-                    &module_info,
-                    &*symbol_registry,
-                    metadata_length,
-                );
                 let mut writer = BufWriter::new(File::create(&output_path)?);
                 obj.write_stream(&mut writer)
                     .map_err(|err| anyhow::anyhow!(err.to_string()))?;
                 writer.flush()?;
-                {
-                    let mut writer = BufWriter::new(File::create("/tmp/main_obj.o")?);
-                    obj.write_stream(&mut writer)
-                        .map_err(|err| anyhow::anyhow!(err.to_string()))?;
-                    writer.flush()?;
-                }
-                let mut writer = BufWriter::new(File::create("func.c")?);
-                writer.write_all(header_file_src.as_bytes())?;
-                writer.flush()?;
-                {
-                    let mut writer = BufWriter::new(File::create("/tmp/func.c")?);
-                    writer.write_all(header_file_src.as_bytes())?;
-                    writer.flush()?;
-                }
-                //link(output_path.clone(), std::path::Path::new("func.c").into())?;
             }
         }