diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..4b49caa --- /dev/null +++ b/.gitignore @@ -0,0 +1,13 @@ +.git +venv +.idea +__pycache__ +test/data/javacores/output/export.xml +test/data/javacores/output/export.xsl +tmp +test/data/javacores-WAIT2/report.xml +test/data/javacores-WAIT2/report.xsl +.vscode +dist +src/javacore_analyser.egg-info +reports \ No newline at end of file diff --git a/.travis.yml b/.travis.yml index 573029c..d5729df 100644 --- a/.travis.yml +++ b/.travis.yml @@ -3,5 +3,8 @@ python: - "3.9" install: - pip install -r requirements.txt +env: + global: + - PYTHONPATH=src:test script: - - python -m unittest test.test_javacore test.test_thread_snapshot test.test_javacore_set test.test_java_thread test.test_stack_trace test.test_javacore_analyzer test.test_tips test.test_verbose_gc_parser test.test_gc_collection test.test_code_snapshot_collection \ No newline at end of file + - python -m unittest test.test_javacore test.test_thread_snapshot test.test_javacore_set test.test_java_thread test.test_stack_trace test.test_javacore_analyser test.test_tips test.test_verbose_gc_parser test.test_gc_collection test.test_code_snapshot_collection \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 396630d..b7c2d5e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -81,16 +81,21 @@ To run the tool with sample data perform the following steps: When the window appears, add the following commandline to **run parameters** `test/data/javacores /tmp/javacoreanalyser_output` Change the second parameter to the directory where you want the output report be created. -2. Right click again on **javacore_analyzer.py** and select **Run** or **Debug**. +2. Right click again on **javacore_analyser.py** and select **Run** or **Debug**. To run web application: -1. Right click on **javacore_analyzer_web.py** directory in **Project** view and select **Modify Run Configuration...**. +1. Right click on **javacore_analyser_web.py** directory in **Project** view and select **Modify Run Configuration...**. 2. Add the following **Environmental variables:** * **DEBUG:True** * **REPORTS_DIR:/tmp/web_reports** You can change the report dir to the location when you want to store the report. The application will start on http://localhost:5000 + +## Build pip package +Follow the steps from [Packaging projects](https://packaging.python.org/en/latest/tutorials/packaging-projects/). +Currently Chris has an API keys for test and production pypi + ## Testing As default the tests in Pycharm are ran in the current selected directory. However we want to run them in main directory of the tool (**javacore-analyser** directory, not **test** directory). diff --git a/README.md b/README.md index f1f5fd2..97d9037 100644 --- a/README.md +++ b/README.md @@ -16,41 +16,57 @@ The tool analyzes Javacores and verbose gc logs and provides some reports like c ## Installation and usage ### Installation: -The tool requires Python 3.9 or higher plus some packages - see more in [REQUIREMENTS](REQUIREMENTS.md). Despite it is not mandatory, it is recommended in Python to use virtual environment to manage packages. +The tool requires Python 3.9 or higher plus some packages - see more in [REQUIREMENTS](REQUIREMENTS.md). +Despite it is not mandatory, it is recommended in Python to use virtual environment to manage packages. + +#### Installing from pip +This is most common option which you will need in 99% of situations Steps: 1. Download and install Python. Usually the latest version is supported. Search for supported versions in [REQUIREMENTS](REQUIREMENTS.md) -2. [Download](https://github.com/IBM/javacore-analyser/releases) and unpack the tool. -3. Create and activate Virtual Environment according to [Creating virtual environments](https://docs.python.org/3/tutorial/venv.html#creating-virtual-environments). -4. Install all required pip packages. Navigate in command line to unpacked tool and type - `pip install -r requirements.txt` +2. Create and activate Virtual Environment according to [Creating virtual environments](https://docs.python.org/3/tutorial/venv.html#creating-virtual-environments). +3. Run the following command: + `pip install javacore-analyser` + OR + `pip install --extra-index-url https://test.pypi.org/simple/ javacore-analyser` - if you want an experimental version + +#### Installing from sources +This is recommended for geeks only: +1. Repeat steps 1 and 2 from above +2. Download the project files either from [Releases](https://github.com/IBM/javacore-analyser/releases) or from [main](https://github.com/IBM/javacore-analyser/archive/refs/heads/main.zip) +3. Extract the code and from code directory execute + `pip install .` ### Running the tool: #### Running cmd application: -1. Activate your created virtual environment according to activate Virtual Environment according to [Creating virtual environments](https://docs.python.org/3/tutorial/venv.html#creating-virtual-environments) -2. Install the requirements using pip: +1. Install application if not done yet +2. Activate your created virtual environment according to activate Virtual Environment according to [Creating virtual environments](https://docs.python.org/3/tutorial/venv.html#creating-virtual-environments) +3. Install the requirements using pip: `pip install requirements.txt` -3. Navigate in command line to unpacked tool and run the following command: - `python javacore_analyzer.py ` +4. Run the following command from cmd: `javacore-analyser-batch ` Where `` is one of the following: * The directory containing javacores and optionally verbose gc * Archive (7z, zip, tar.gz, tar.bz2) containing the same -* List of the javacores separated by `'` character. Optionally you can add `--separator` option to define your own separator. +* List of the javacores separated by `;` character. Optionally you can add `--separator` option to define your own separator. You can type the following command to obtain the help: -`python javacore_analyzer.py --help` +`javacore-analyser-batch --help` #### Running web application: -1. Repeat steps 1 and 2 from cmd application -2. Navigate to unpacked tool and run the following commands: +1. Repeat steps 1-3 from cmd application +2. OPTIONAL: set the following variables: ``` export REPORTS_DIR=/tmp/reports - flask --app javacore_analyser_web run + export PORT=5000 ``` - The first command sets the location of the generated reports stored. - The second command starts the server which can be accessed by navigating to http://localhost:5000 + The first parameter sets where the reports need to be stored. If not set, then the `reports` dir will be created in current location. + The first parameter set the port to use by application. If not specified, 5000 will be used. +3. Execute the following command from cmd: + `javacore_analyser_web` + Now you can type (http://localhost:5000/). +