feat(build): include manual file in packages MONGOSH-1017 (#1144)

Author: mabaasit

config/build.conf.js

@@ -8,6 +8,11 @@ const os = require('os');
  */
 const ROOT = path.join(__dirname, '..');
 
+/**
+ * The tmp folder location.
+ */
+ const TMP_DIR = path.join(ROOT, 'tmp');
+
 /**
  * The mongosh package.
  */
@@ -44,7 +49,7 @@ const EXECUTABLE_PATH = path.join(OUTPUT_DIR, process.platform === 'win32' ? 'mo
  * We use the name mongocryptd-mongosh to avoid conflicts with users
  * potentially installing the 'proper' mongocryptd package.
  */
-const MONGOCRYPTD_PATH = path.resolve(__dirname, '..', 'tmp', 'mongocryptd-mongosh' + (process.platform === 'win32' ? '.exe' : ''));
+const MONGOCRYPTD_PATH = path.resolve(TMP_DIR, 'mongocryptd-mongosh' + (process.platform === 'win32' ? '.exe' : ''));
 
 /**
  * Build info JSON data file.
@@ -66,6 +71,11 @@ const REVISION = process.env.GITHUB_COMMIT ?? process.env.REVISION;
  */
 const COPYRIGHT = `${new Date().getYear() + 1900} MongoDB, Inc.`;
 
+/**
+ * The manual page file name
+ */
+const MANPAGE_NAME = 'mongosh.1.gz'
+
 /**
  * Export the configuration for the build.
  */
@@ -141,6 +151,10 @@ module.exports = {
         packagedFilePath: 'THIRD_PARTY_NOTICES'
       }
     ],
+    manpage: {
+      sourceFilePath: path.resolve(TMP_DIR, 'manpage', MANPAGE_NAME),
+      packagedFilePath: MANPAGE_NAME,
+    },
     metadata: {
       name: 'mongosh',
       rpmName: 'mongodb-mongosh',
@@ -159,5 +173,10 @@ module.exports = {
     debTemplateDir: path.resolve(__dirname, '..', 'packaging', 'deb-template'),
     rpmTemplateDir: path.resolve(__dirname, '..', 'packaging', 'rpm-template'),
     msiTemplateDir: path.resolve(__dirname, '..', 'packaging', 'msi-template')
-  }
+  },
+  manpage: {
+    sourceUrl: 'https://docs.mongodb.com/mongodb-shell/manpages.tar.gz',
+    downloadPath: path.resolve(TMP_DIR, 'manpage'),
+    fileName: MANPAGE_NAME,
+  },
 };

packages/build/src/config/config.ts

@@ -1,6 +1,12 @@
 import type { PackageInformation } from '../packaging/package';
 import { BuildVariant } from './build-variant';
 
+interface ManPageConfig {
+  sourceUrl: string;
+  downloadPath: string;
+  fileName: string;
+}
+
 /**
  * Defines the configuration interface for the build system.
  */
@@ -42,4 +48,5 @@ export interface Config {
   mongocryptdPath: string;
   packageInformation?: PackageInformation;
   artifactUrlFile?: string;
+  manpage?: ManPageConfig;
 }

packages/build/src/packaging/download-manpage.spec.ts

@@ -0,0 +1,20 @@
+import nock from 'nock';
+import { join } from 'path';
+import { promises as fs } from 'fs';
+import { downloadManpage } from './download-manpage';
+
+describe('packaging download manpage', () => {
+  it('downloads manpage', async() => {
+    nock('http://example.com')
+      .get('/')
+      .replyWithFile(
+        200,
+        join(__dirname, '..', '..', 'test', 'fixtures', 'manpages.tar.gz')
+      );
+
+    const destination = join(__dirname, '..', '..', 'tmp', 'manpage');
+    const name = 'manpages.gz';
+    await downloadManpage('http://example.com', destination, name);
+    await fs.access(join(destination, name));
+  });
+});

packages/build/src/packaging/download-manpage.ts

@@ -0,0 +1,22 @@
+import fetch from 'node-fetch';
+import tar from 'tar';
+import { createReadStream, createWriteStream, promises as fs } from 'fs';
+import { promisify } from 'util';
+import { join } from 'path';
+import { pipeline } from 'stream';
+import { createGzip } from 'zlib';
+
+export async function downloadManpage(url: string, destination: string, name: string) {
+  await fs.mkdir(destination, { recursive: true });
+  const response = await fetch(url);
+  await promisify(pipeline)(
+    response.body,
+    tar.x({ cwd: destination })
+  );
+  await promisify(pipeline)(
+    createReadStream(join(destination, 'mongosh.1')),
+    createGzip(),
+    createWriteStream(join(destination, name))
+  );
+  console.info(`Saved manpage: ${join(destination, name)}`);
+}

packages/build/src/packaging/package/debian.spec.ts

@@ -30,6 +30,7 @@ describe('tarball debian', () => {
       expect(stdout).to.match(/^-rw-r.-r--.+\/usr\/share\/doc\/foobar\/LICENSE_foo$/m);
       expect(stdout).to.match(/^-rw-r.-r--.+\/usr\/share\/doc\/foobar\/README$/m);
       expect(stdout).to.match(/^-rw-r.-r--.+\/usr\/share\/doc\/foobar\/copyright$/m);
+      expect(stdout).to.match(/^-rw-r.-r--.+\/usr\/share\/man\/man1\/mongosh.1.gz$/m);
     }
     {
       const { stdout } = await execFile('dpkg', ['-I', tarball.path]);

packages/build/src/packaging/package/debian.ts

@@ -35,6 +35,14 @@ export async function createDebianPackage(
   for (const { sourceFilePath, packagedFilePath } of docFiles) {
     await fs.copyFile(sourceFilePath, path.join(docdir, packagedFilePath), COPYFILE_FICLONE);
   }
+
+  if (pkg.manpage) {
+    // Put manpage file in /usr/share/man/man1/.
+    const manualDir = path.join(dir, pkg.metadata.debName, 'usr', 'share', 'man', 'man1');
+    await fs.mkdir(manualDir, { recursive: true });
+    await fs.copyFile(pkg.manpage.sourceFilePath, path.join(manualDir, pkg.manpage.packagedFilePath), COPYFILE_FICLONE);
+  }
+
   // Debian packages should contain a 'copyright' file.
   // https://www.debian.org/doc/debian-policy/ch-archive.html#s-pkgcopyright
   await fs.writeFile(path.join(docdir, 'copyright'), await generateDebianCopyright(pkg));

packages/build/src/packaging/package/helpers.ts

@@ -34,8 +34,12 @@ export async function createCompressedArchiveContents(archiveRootName: string, p
   await fs.mkdir(archiveRoot, { recursive: true });
   const docFiles = [
     ...pkg.otherDocFilePaths,
-    ...pkg.binaries.map(({ license }) => license)
+    ...pkg.binaries.map(({ license }) => license),
   ];
+  if (pkg.manpage) {
+    docFiles.push(pkg.manpage);
+  }
+
   for (const { sourceFilePath, packagedFilePath } of docFiles) {
     await fs.copyFile(sourceFilePath, path.join(archiveRoot, packagedFilePath), COPYFILE_FICLONE);
   }

packages/build/src/packaging/package/package-information.ts

@@ -9,6 +9,8 @@ interface LicenseInformation extends DocumentationFile {
     rpmIdentifier: string;
 }
 
+type ManPage = DocumentationFile;
+
 // This is filled in by the build config file.
 export interface PackageInformation {
     binaries: {
@@ -17,6 +19,7 @@ export interface PackageInformation {
         license: LicenseInformation;
     }[];
     otherDocFilePaths: DocumentationFile[];
+    manpage?: ManPage;
     metadata: {
         name: string;
         debName: string;

packages/build/src/packaging/package/redhat.spec.ts

@@ -38,6 +38,7 @@ describe('tarball redhat', () => {
     expect(stdout).to.match(/^\/usr\/share\/doc\/foobar-1.0.0\/README$/m);
     expect(stdout).to.match(/^\/usr\/share\/licenses\/foobar-1.0.0\/LICENSE_bar$/m);
     expect(stdout).to.match(/^\/usr\/share\/licenses\/foobar-1.0.0\/LICENSE_foo$/m);
+    expect(stdout).to.match(/^\/usr\/share\/man\/man1\/mongosh.1.gz$/m);
   });
 
   it('determines and copies created RPM', async() => {

packages/build/src/packaging/package/redhat.ts

@@ -35,14 +35,17 @@ export async function createRedhatPackage(
   const filelistRpm = [
     ...pkg.binaries.map(({ sourceFilePath, category }) => `%{_${category}dir}/${path.basename(sourceFilePath)}`),
     ...pkg.binaries.map(({ license }) => `%license ${license.packagedFilePath}`),
-    ...pkg.otherDocFilePaths.map(({ packagedFilePath }) => `%doc ${packagedFilePath}`)
-  ].join('\n');
+    ...pkg.otherDocFilePaths.map(({ packagedFilePath }) => `%doc ${packagedFilePath}`),
+  ];
+  if (pkg.manpage) {
+    filelistRpm.push(`%doc ${pkg.manpage.packagedFilePath}`);
+  }
   const version = sanitizeVersion(pkg.metadata.version, 'rpm');
   const dir = await generateDirFromTemplate(templateDir, {
     ...pkg.metadata,
     licenseRpm,
     installscriptRpm,
-    filelistRpm,
+    filelistRpm: filelistRpm.join('\n'),
     version
   });
   // Copy all files that we want to ship into the BUILD directory.
@@ -56,6 +59,10 @@ export async function createRedhatPackage(
     await fs.copyFile(sourceFilePath, path.join(dir, 'BUILD', packagedFilePath), COPYFILE_FICLONE);
   }
 
+  if (pkg.manpage) {
+    await fs.copyFile(pkg.manpage.sourceFilePath, path.join(dir, 'BUILD', pkg.manpage.packagedFilePath), COPYFILE_FICLONE);
+  }
+
   // Create the package.
   await execFile('rpmbuild', [
     '-bb', path.join(dir, 'SPECS', `${pkg.metadata.rpmName}.spec`),