From f582007d6490d649442810ec59395e1541289957 Mon Sep 17 00:00:00 2001 From: Shannon Weyrick Date: Sat, 19 Dec 2020 11:43:46 -0500 Subject: [PATCH] Improve READMEs, other minor improvements (#25) * readme prep, reorganize docker a bit. add missing dep * add contribute --- .dockerignore | 1 + .gitignore | 6 +- 3rd/EndianPortable/EndianPortable.h | 210 ++++++++++++++++++++++++++++ 3rd/README.md | 0 CONTRIBUTING.md | 85 +++++++++++ README.md | 4 +- cmd/README.md | 0 Dockerfile => docker/Dockerfile | 7 +- entry.sh => docker/entry.sh | 0 reporting/README.md | 0 src/README.md | 1 + tests/README.md | 0 tests/external.sh | 2 +- 13 files changed, 308 insertions(+), 8 deletions(-) create mode 100644 .dockerignore create mode 100644 3rd/EndianPortable/EndianPortable.h create mode 100644 3rd/README.md create mode 100644 CONTRIBUTING.md create mode 100644 cmd/README.md rename Dockerfile => docker/Dockerfile (88%) rename entry.sh => docker/entry.sh (100%) create mode 100644 reporting/README.md create mode 100644 src/README.md create mode 100644 tests/README.md diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 000000000..23fa6d8a5 --- /dev/null +++ b/.dockerignore @@ -0,0 +1 @@ +tests/external diff --git a/.gitignore b/.gitignore index 8f5f082f3..4fba77581 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,5 @@ -.idea/ +.idea* cmake-build-*/ -cmd/.idea/ +.DS_Store* +docs/html-documentation-generated* +tests/external diff --git a/3rd/EndianPortable/EndianPortable.h b/3rd/EndianPortable/EndianPortable.h new file mode 100644 index 000000000..2f0f19d29 --- /dev/null +++ b/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 +#elif defined __GLIBC__ + #include + #ifndef be64toh + /* Support older glibc (<2.9) which lack be64toh */ + #include + #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 +#elif defined(WIN32) || defined(WINx64) +#include + #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 +#elif defined sun + #include + #include +#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 + #include +#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 + +#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 +#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_ */ diff --git a/3rd/README.md b/3rd/README.md new file mode 100644 index 000000000..e69de29bb diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..262edf8c3 --- /dev/null +++ b/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 support@ns1.com 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. \ No newline at end of file diff --git a/README.md b/README.md index 7f1846061..3b023ae97 100644 --- a/README.md +++ b/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 diff --git a/cmd/README.md b/cmd/README.md new file mode 100644 index 000000000..e69de29bb diff --git a/Dockerfile b/docker/Dockerfile similarity index 88% rename from Dockerfile rename to docker/Dockerfile index dee8e7d47..f43211771 100644 --- a/Dockerfile +++ b/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" ] diff --git a/entry.sh b/docker/entry.sh similarity index 100% rename from entry.sh rename to docker/entry.sh diff --git a/reporting/README.md b/reporting/README.md new file mode 100644 index 000000000..e69de29bb diff --git a/src/README.md b/src/README.md new file mode 100644 index 000000000..1026ea858 --- /dev/null +++ b/src/README.md @@ -0,0 +1 @@ +https://github.com/ns1/pktvisor/projects/1#card-51299219 \ No newline at end of file diff --git a/tests/README.md b/tests/README.md new file mode 100644 index 000000000..e69de29bb diff --git a/tests/external.sh b/tests/external.sh index c13ec7b87..f9d95768b 100755 --- a/tests/external.sh +++ b/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