Improve READMEs, other minor improvements (#25)

* readme prep, reorganize docker a bit. add missing dep

* add contribute

.dockerignore

@@ -0,0 +1 @@
+tests/external

.gitignore

@@ -1,3 +1,5 @@
-.idea/
+.idea*
 cmake-build-*/
-cmd/.idea/
+.DS_Store*
+docs/html-documentation-generated*
+tests/external

3rd/EndianPortable/EndianPortable.h

@@ -0,0 +1,210 @@
+/*
+ * librdkafka - Apache Kafka C library
+ *
+ * Copyright (c) 2012-2015 Magnus Edenhill
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+#ifndef _ENDIANPORTABLE_H_
+#define _ENDIANPORTABLE_H_
+
+/**
+ * Provides portable endian-swapping macros/functions.
+ *
+ *   be64toh()
+ *   htobe64()
+ *   be32toh()
+ *   htobe32()
+ *   be16toh()
+ *   htobe16()
+ *   le64toh()
+ */
+
+#ifdef __FreeBSD__
+  #include <sys/endian.h>
+#elif defined __GLIBC__
+  #include <endian.h>
+ #ifndef be64toh
+   /* Support older glibc (<2.9) which lack be64toh */
+  #include <byteswap.h>
+  #if __BYTE_ORDER == __BIG_ENDIAN
+   #define be16toh(x) (x)
+   #define be32toh(x) (x)
+   #define be64toh(x) (x)
+   #define le64toh(x) __bswap_64 (x)
+   #define le32toh(x) __bswap_32 (x)
+  #else
+   #define be16toh(x) __bswap_16 (x)
+   #define be32toh(x) __bswap_32 (x)
+   #define be64toh(x) __bswap_64 (x)
+   #define le64toh(x) (x)
+   #define le32toh(x) (x)
+  #endif
+ #endif
+
+#elif defined __CYGWIN__
+ #include <endian.h>
+#elif defined(WIN32) || defined(WINx64)
+#include <winsock2.h>
+ #if(BYTE_ORDER == LITTLE_ENDIAN)
+  #define htobe16(x) htons(x)
+  #define htole16(x) (x)
+  #define be16toh(x) ntohs(x)
+  #define le16toh(x) (x)
+
+  #define htobe32(x) htonl(x)
+  #define htole32(x) (x)
+  #define be32toh(x) ntohl(x)
+  #define le32toh(x) (x)
+
+  #define htobe64(x) htonll(x)
+  #define htole64(x) (x)
+  #define be64toh(x) ntohll(x)
+  #define le64toh(x) (x)
+ #else
+  #define htobe16(x) (x)
+  #define htole16(x) __builtin_bswap16(x)
+  #define be16toh(x) (x)
+  #define le16toh(x) __builtin_bswap16(x)
+
+  #define htobe32(x) (x)
+  #define htole32(x) __builtin_bswap32(x)
+  #define be32toh(x) (x)
+  #define le32toh(x) __builtin_bswap32(x)
+
+  #define htobe64(x) (x)
+  #define htole64(x) __builtin_bswap64(x)
+  #define be64toh(x) (x)
+  #define le64toh(x) __builtin_bswap64(x)
+ #endif
+#elif defined __BSD__
+  #include <sys/endian.h>
+#elif defined sun
+  #include <sys/byteorder.h>
+  #include <sys/isa_defs.h>
+#define __LITTLE_ENDIAN 1234
+#define __BIG_ENDIAN 4321
+#ifdef _BIG_ENDIAN
+#define __BYTE_ORDER __BIG_ENDIAN
+#define be64toh(x) (x)
+#define be32toh(x) (x)
+#define be16toh(x) (x)
+#define le16toh(x) ((uint16_t)BSWAP_16(x))
+#define le32toh(x) BSWAP_32(x)
+#define le64toh(x) BSWAP_64(x)
+# else
+#define __BYTE_ORDER __LITTLE_ENDIAN
+#define be64toh(x) BSWAP_64(x)
+#define be32toh(x) ntohl(x)
+#define be16toh(x) ntohs(x)
+#define le16toh(x) (x)
+#define le32toh(x) (x)
+#define le64toh(x) (x)
+#define htole16(x) (x)
+#define htole64(x) (x)
+#endif /* sun */
+
+#elif defined __APPLE__
+  #include <machine/endian.h>
+  #include <libkern/OSByteOrder.h>
+#if __DARWIN_BYTE_ORDER == __DARWIN_BIG_ENDIAN
+#define be64toh(x) (x)
+#define be32toh(x) (x)
+#define be16toh(x) (x)
+#define le16toh(x) OSSwapInt16(x)
+#define le32toh(x) OSSwapInt32(x)
+#define le64toh(x) OSSwapInt64(x)
+#else
+#define be64toh(x) OSSwapInt64(x)
+#define be32toh(x) OSSwapInt32(x)
+#define be16toh(x) OSSwapInt16(x)
+#define le16toh(x) (x)
+#define le32toh(x) (x)
+#define le64toh(x) (x)
+#endif
+
+#elif defined(_MSC_VER)
+#include <intrin.h>
+
+#define be64toh(x) _byteswap_uint64(x)
+#define be32toh(x) _byteswap_ulong(x)
+#define be16toh(x) _byteswap_ushort(x)
+#define le16toh(x) (x)
+#define le32toh(x) (x)
+#define le64toh(x) (x)
+
+#elif defined _AIX      /* AIX is always big endian */
+#define be64toh(x) (x)
+#define be32toh(x) (x)
+#define be16toh(x) (x)
+#define le32toh(x)                              \
+        ((((x) & 0xff) << 24) |                 \
+         (((x) & 0xff00) << 8) |                \
+         (((x) & 0xff0000) >> 8) |              \
+         (((x) & 0xff000000) >> 24))
+#define le64toh(x)                               \
+        ((((x) & 0x00000000000000ffL) << 56) |   \
+         (((x) & 0x000000000000ff00L) << 40) |   \
+         (((x) & 0x0000000000ff0000L) << 24) |   \
+         (((x) & 0x00000000ff000000L) << 8)  |   \
+         (((x) & 0x000000ff00000000L) >> 8)  |   \
+         (((x) & 0x0000ff0000000000L) >> 24) |   \
+         (((x) & 0x00ff000000000000L) >> 40) |   \
+         (((x) & 0xff00000000000000L) >> 56))
+#else
+ #include <endian.h>
+#endif
+
+
+
+/*
+ * On Solaris, be64toh is a function, not a macro, so there's no need to error
+ * if it's not defined.
+ */
+#if !defined(__sun) && !defined(be64toh)
+#error Missing definition for be64toh
+#endif
+
+#ifndef be32toh
+#define be32toh(x) ntohl(x)
+#endif
+
+#ifndef be16toh
+#define be16toh(x) ntohs(x)
+#endif
+
+#ifndef htobe64
+#define htobe64(x) be64toh(x)
+#endif
+#ifndef htobe32
+#define htobe32(x) be32toh(x)
+#endif
+#ifndef htobe16
+#define htobe16(x) be16toh(x)
+#endif
+
+#ifndef htole32
+#define htole32(x) le32toh(x)
+#endif
+
+#endif /* _ENDIANPORTABLE_H_ */ 

CONTRIBUTING.md

@@ -0,0 +1,85 @@
+## How to Contribute
+At NS1, it makes us very happy to get pull requests, and we appreciate the time
+and effort it takes to put one together. Below are a few guidelines that can
+help get your pull request approved and merged quickly and easily.
+
+It's important to note that the guidelines are recommendations, not
+requirements. You may submit a pull request that does not adhere to the
+guidelines, but ideation and development may take longer or be more involved.
+
+* Avoid getting nitpicked for basic formatting. Match the style of any given
+  file as best you can - tabs or spaces as appropriate, curly bracket
+  placement, indentation style, line length, etc. If there are any linters
+  mentioned in docs or Makefile, please run them.
+
+* Avoid changes that have any possibility of breaking existing uses. Some of
+  these codebases have many of users, doing creative things with them. Breaking
+  changes can cause significant challenges for other users. It's important to
+  note that some projects are dependencies of other projects, and changes may
+  require cross-code base coordination. It can be challenging to identify if a
+  small change will have large ramifications, so we mainly ask that you keep
+  this in mind when writing or modifying code. Do your best to preserve
+  interfaces, and understand that NS1 may need to reject pull requests if they
+  would jeopardize platform stability or place an undue burden on other users.
+
+* If there are unit and/or integration tests, keeping the test suites passing
+  is a must before we can merge. And nice tests around the changes will
+  definitely help get a patch merged quickly.
+
+* Ensure that any documentation that is part of the project is updated as part
+  of the pull request. This helps to expedite the merge process.
+
+* Be considerate when introducing new dependencies to a project. If a new
+  dependency is necessary, try to choose a well-known project, and to pin the
+  version as specifically as possible.
+
+## Opening an issue
+
+Below are a few guidelines for opening an issue on one of NS1's open-source
+repositories. Adhering to these guidelines to the best of your ability will
+help ensure that requests are resolved quickly and efficiently.
+
+* **Be specific about the problem.** When describing your issue, it's helpful
+  to include as many details as you can about the expected behavior versus
+  what happened or is happening instead.
+* **Be specific about your objective.** Help us understand exactly what you are
+  trying to accomplish so that our developers have a clear understanding about
+  the particular problem you are trying to solve. In other words, help us
+  avoid the "[XY Problem](http://xyproblem.info)".
+* **Indicate which products, software versions, and programming languages you
+  are using.** In your request, indicate which NS1 product(s) you're using and,
+  if relevant, which versions you are running. Also include any third-party
+  software and versions that are relevant to the issue. If not obvious, include
+  which programming language(s) you are using.
+* **If possible, provide a reproducible example of the problem.** This allows
+  us to better examine the issue and test solutions.
+* **If possible, include stack/error traces.** Note: ensure there is no
+  sensitive included in your stack/error traces.
+
+## Closing an issue
+
+* If an issue is closed by a commit, reference the relevant PR or commit when
+  closing.
+* If an issue is closed by NS1 for any reason, you should expect us to include
+  a reason for it.
+* If the fix does not work or is incomplete, you are welcome to re-open or
+  recreate the issue. When doing so, it's important to be clear about why the
+  previous fix was inadequate, to clarify the previous problem statement,
+  and/or to modify the scope of the request. Please keep in mind that project
+  status consideration or conflicting priorities may require us to close or
+  defer work on the new or reopened issue. If that happens, feel free to reach
+  out of [email protected] for more information.
+
+## Tags on issues
+
+In some projects we (NS1) may apply basic tags on some issues, for
+organizational purposes. Note: we do not use tags to indicate timelines or
+priorities.
+
+Here are definitions for the most common tags we use:
+
+* **BUG** - This tag confirms that the issue is a bug we intend to fix. The
+  issue will remain open until it is resolved.
+* **ENHANCEMENT** - This tag indicates that we have categorized the issue as a
+  feature request. Depending on priorities and timelines, we may close issues
+  with this tag and track them in our internal backlog instead.

README.md

@@ -157,12 +157,12 @@ cmake ..
 make
 ```
 
-Building the docker image:
+Building the docker image (from the root project directory):
 ```
 org="myorg"
 image="mypktvisor"
 tag="latest"
-docker build -t ${org}/${image}:${tag} -f Dockerfile .
+docker build -t ${org}/${image}:${tag} -f docker/Dockerfile .
 ```
 
 Contributions

Dockerfile → docker/Dockerfile

@@ -30,7 +30,8 @@ RUN \
     go get github.com/pkg/errors && \
     go get github.com/jroimartin/gocui && \
     go get github.com/docopt/docopt-go && \
-    go build /src/cmd/pktvisor/pktvisor.go
+    cd /src/cmd/pktvisor && \
+    go build
 
 FROM debian:buster-slim AS runtime
 
@@ -42,8 +43,8 @@ RUN \
     rm -rf /var/lib/apt
 
 COPY --from=build /tmp/build/pktvisord /usr/local/sbin/pktvisord
-COPY --from=build /tmp/build/pktvisor /usr/local/bin/pktvisor
-COPY entry.sh /usr/local/bin/
+COPY --from=build /src/cmd/pktvisor/pktvisor /usr/local/bin/pktvisor
+COPY docker/entry.sh /usr/local/bin/
 
 ENTRYPOINT [ "entry.sh" ]
 

src/README.md

@@ -0,0 +1 @@
+https://github.com/ns1/pktvisor/projects/1#card-51299219

tests/external.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/bin/bash -x
 
 # if a file called external/run.sh exists, run it.
 FILE=external/run.sh